> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Shipping Promotion Code Samples

## Buy two of X and buy two of Y and get free shipping to all zones start/end times (AND operator)

#### Request

**`Example request`**

```json title="Example request"
{
  "name": "Buy two of X, buy two of Y and get free shipping to all zones",
  "redemption_type": "AUTOMATIC",
  "rules": [
    {
      "action": {
        "shipping": {
          "free_shipping": true,
          "zone_ids": "*"
        }
      },
      "apply_once": true,
      "stop": false,
      "currency_code": "AUD",
      "condition": {
        "and": [
          {
            "cart": {
              "items": {
                "products": [
                  118
                ]
              },
              "minimum_quantity": 2
            }
          },
          {
            "cart": {
              "items": {
                "variants": [
                  134
                ]
              },
              "minimum_quantity": 2
            }
          }
        ]
      }
    }
  ],
  "notifications": [],
  "stop": false,
  "status": "ENABLED",
  "start_date": "2019-02-06T05:00:00+00:00",
  "end_date": "2019-02-09T04:59:59+00:00"
}
```

#### Response

**`Example response`**

```json title="Example response"
{
  "data": {
    "id": 54,
    "name": "Buy two of X, buy two of Y and get free shipping to all zones",
    "created_from": "api",
    "customer": {
      "group_ids": [],
      "minimum_order_count": 0,
      "excluded_group_ids": [],
      "segments": null
    },
    "rules": [
      {
        "action": {
          "shipping": {
            "free_shipping": true,
            "zone_ids": "*"
          }
        },
        "apply_once": true,
        "stop": false,
        "condition": {
          "and": [
            {
              "cart": {
                "items": {
                  "products": [
                    118
                  ]
                },
                "minimum_quantity": 2
              }
            },
            {
              "cart": {
                "items": {
                  "variants": [
                    134
                  ]
                },
                "minimum_quantity": 2
              }
            }
          ]
        }
      }
    ],
    "notifications": [],
    "stop": false,
    "currency_code": "USD",
    "redemption_type": "AUTOMATIC",
    "shipping_address": null,
    "current_uses": 0,
    "max_uses": null,
    "start_date": "2019-02-06T05:00:00+00:00",
    "end_date": "2019-02-09T04:59:59+00:00",
    "status": "ENABLED",
    "schedule": null,
    "can_be_used_with_other_promotions": true
  },
  "meta": {}
}
```

## Order at least X units of product Y and get free shipping to specific shipping zones

#### Request

**`Example request`**

```json title="Example request" showLineNumbers={false}
{
  "name": "Order at least X units of product Y and get free shipping to specific shipping zones",
  "redemption_type": "AUTOMATIC",
  "rules": [
    {
      "action": {
        "shipping": {
          "free_shipping": true,
          "zone_ids": [
            2,
            3
          ]
        }
      },
      "apply_once": true,
      "stop": false,
      "condition": {
        "cart": {
          "items": {
            "products": [
              129
            ]
          },
          "minimum_quantity": 1
        }
      }
    }
  ],
  "notifications": [
    {
      "type": "UPSELL",
      "content": "Get free shipping for purchasing Twine Stand with Cutter. Limited to first 50 customers!\r\n<div>&nbsp;</div>",
      "locations": [
        "HOME_PAGE",
        "PRODUCT_PAGE",
        "CART_PAGE",
        "CHECKOUT_PAGE"
      ]
    },
    {
      "type": "ELIGIBLE",
      "content": "You are eligible for free shipping.\r\n<div>&nbsp;</div>",
      "locations": [
        "CART_PAGE"
      ]
    },
    {
      "type": "APPLIED",
      "content": "Congratulations you get free shipping!\r\n<div>&nbsp;</div>",
      "locations": [
        "CART_PAGE"
      ]
    }
  ],
  "stop": false,
  "max_uses": 50,
  "start_date": "2019-02-01T05:00:00+00:00",
  "end_date": "2019-02-05T04:59:59+00:00",
  "status": "ENABLED"
}
```

#### Response

**`Example response`**

```json title="Example response"
{
  "data": {
    "id": 44,
    "name": "Order at least X units of product Y and get free shipping to specific shipping zones",
    "created_from": "api",
    "customer": {
      "group_ids": [],
      "minimum_order_count": 0,
      "excluded_group_ids": [],
      "segments": null
    },
    "rules": [
      {
        "action": {
          "shipping": {
            "free_shipping": true,
            "zone_ids": [
              2,
              3
            ]
          }
        },
        "apply_once": true,
        "stop": false,
        "condition": {
          "cart": {
            "items": {
              "products": [
                129
              ]
            },
            "minimum_quantity": 1
          }
        }
      }
    ],
    "notifications": [
      {
        "type": "UPSELL",
        "content": "Get free shipping for purchasing Twine Stand with Cutter. Limited to first 50 customers!\r\n<div>&nbsp;</div>",
        "locations": [
          "HOME_PAGE",
          "PRODUCT_PAGE",
          "CART_PAGE",
          "CHECKOUT_PAGE"
        ]
      },
      {
        "type": "ELIGIBLE",
        "content": "You are eligible for free shipping.\r\n<div>&nbsp;</div>",
        "locations": [
          "CART_PAGE"
        ]
      },
      {
        "type": "APPLIED",
        "content": "Congratulations you get free shipping!\r\n<div>&nbsp;</div>",
        "locations": [
          "CART_PAGE"
        ]
      }
    ],
    "stop": false,
    "currency_code": "USD",
    "redemption_type": "AUTOMATIC",
    "shipping_address": null,
    "current_uses": 0,
    "max_uses": 50,
    "start_date": "2019-02-01T05:00:00+00:00",
    "end_date": "2019-02-05T04:59:59+00:00",
    "status": "ENABLED",
    "schedule": null,
    "can_be_used_with_other_promotions": true
  },
  "meta": {}
}
```

## Order at least 2X of product and get free shipping

#### Request

**`Example request`**

```json title="Example request"
{
  "name": "Order at least 2X of product and get free shipping",
  "redemption_type": "AUTOMATIC",
  "rules": [
    {
      "action": {
        "shipping": {
          "free_shipping": true,
          "zone_ids": "*"
        }
      },
      "apply_once": true,
      "stop": false,
      "condition": {
        "cart": {
          "items": {
            "products": [
              129
            ]
          },
          "minimum_quantity": 2
        }
      }
    }
  ],
  "notifications": [
    {
      "type": "UPSELL",
      "content": "<div>&nbsp;</div>",
      "locations": [
        "CART_PAGE"
      ]
    },
    {
      "type": "ELIGIBLE",
      "content": "<div>&nbsp;</div>",
      "locations": [
        "CART_PAGE"
      ]
    },
    {
      "type": "APPLIED",
      "content": "<div>&nbsp;</div>",
      "locations": [
        "CART_PAGE"
      ]
    }
  ],
  "stop": false,
  "status": "ENABLED",
  "start_date": "2019-02-06T05:00:00+00:00",
  "end_date": "2019-02-09T04:59:59+00:00"
}
```

#### Response

**`Example response`**

```json title="Example response"
{
  "data": {
    "id": 45,
    "name": "Order at least 2X of product and get free shipping",
    "created_from": "api",
    "customer": {
      "group_ids": [],
      "minimum_order_count": 0,
      "excluded_group_ids": [],
      "segments": null
    },
    "rules": [
      {
        "action": {
          "shipping": {
            "free_shipping": true,
            "zone_ids": "*"
          }
        },
        "apply_once": true,
        "stop": false,
        "condition": {
          "cart": {
            "items": {
              "products": [
                129
              ]
            },
            "minimum_quantity": 2
          }
        }
      }
    ],
    "notifications": [
      {
        "type": "UPSELL",
        "content": "<div>&nbsp;</div>",
        "locations": [
          "CART_PAGE"
        ]
      },
      {
        "type": "ELIGIBLE",
        "content": "<div>&nbsp;</div>",
        "locations": [
          "CART_PAGE"
        ]
      },
      {
        "type": "APPLIED",
        "content": "<div>&nbsp;</div>",
        "locations": [
          "CART_PAGE"
        ]
      }
    ],
    "stop": false,
    "currency_code": "USD",
    "redemption_type": "AUTOMATIC",
    "shipping_address": null,
    "current_uses": 0,
    "max_uses": null,
    "start_date": "2019-02-06T05:00:00+00:00",
    "end_date": "2019-02-09T04:59:59+00:00",
    "status": "ENABLED",
    "schedule": null,
    "can_be_used_with_other_promotions": true
  },
  "meta": {}
}
```

## Spend at least \$100 and get \$10 off shipping (specific methods)

#### Request

**`Example request`**

```json title="Example request"
{
  "name": "Spend at least $100 and get $10 off shipping (specific methods)",
  "redemption_type": "AUTOMATIC",
  "rules": [
    {
      "action": {
        "shipping_discount": {
          "discount": { "fixed_amount": 10 },
          "method_ids": [1, 3]
        }
      },
      "apply_once": true,
      "stop": false,
      "condition": { "cart": { "minimum_spend": 100 } }
    }
  ],
  "notifications": [],
  "stop": false,
  "status": "ENABLED",
  "currency_code": "USD",
  "start_date": "2025-10-01T00:00:00-05:00",
  "end_date": null
}
```

#### Response

**`Example response`**

```json title="Example response"
  {
  "data": {
    "id": 1,
    "name": "Spend at least $100 and get $10 off shipping (specific methods)",
    "created_from": "api",
    "customer": {
      "group_ids": [],
      "minimum_order_count": 0,
      "excluded_group_ids": [],
      "segments": null
    },
    "rules": [
      {
        "action": {
          "shipping_discount": {
            "discount": { "fixed_amount": "10" },
            "method_ids": [1, 3]
          }
        },
        "apply_once": true,
        "stop": false,
        "condition": { "cart": { "minimum_spend": "100" } }
      }
    ],
    "notifications": [],
    "stop": false,
    "currency_code": "USD",
    "redemption_type": "AUTOMATIC",
    "shipping_address": null,
    "current_uses": 0,
    "max_uses": null,
    "start_date": "2025-10-01T05:00:00+00:00",
    "end_date": null,
    "status": "ENABLED",
    "schedule": null,
    "can_be_used_with_other_promotions": true
  },
  "meta": {}
}
```

## Get 10% off on shipping up to \$15 (limited discount maximum)

#### Request

**`Example request`**

```json title="Example request"
{
  "can_be_used_with_other_promotions": true,
  "channels": [],
  "coupon_overrides_automatic_when_offering_higher_discounts": false,
  "currency_code": "USD",
  "current_uses": 0,
  "created_from": "api",
  "customer": {
    "group_ids": [],
    "minimum_order_count": 0,
    "segments": null,
    "excluded_group_ids": []
  },
  "end_date": null,
  "max_uses": null,
  "name": "discount on shipping - percent",
  "notifications": [],
  "redemption_type": "AUTOMATIC",
  "rules": [
    {
      "action": {
      "shipping_discount": {
        "discount": {
          "percentage_amount": "10"
        },
        "maximum_allowed_discount_amount": "15",
        "method_ids": "*"
      }
    },
    "apply_once": true,
    "stop": false
    }
  ],
  "schedule": null,
  "shipping_address": null,
  "start_date": "2025-10-15T00:00:00-05:00",
  "status": "ENABLED",
  "display_name": "Get 10% off on shipping upto $15"
}
```

#### Response

**`Example response`**

```json title="Example response"
  {
    "data": {
    "id": 134,
    "name": "discount on shipping - percent",
    "channels": [],
    "created_from": "api",
    "customer": {
      "group_ids": [],
      "minimum_order_count": 0,
      "excluded_group_ids": [],
      "segments": null
    },
    "rules": [
      {
        "action": {
          "shipping_discount": {
            "discount": {
              "percentage_amount": "10"
            },
            "maximum_allowed_discount_amount": "15",
            "method_ids": "*"
          }
        },
        "apply_once": true,
        "stop": false
      }
    ],
    "notifications": [],
    "stop": false,
    "currency_code": "USD",
    "redemption_type": "AUTOMATIC",
    "shipping_address": null,
    "current_uses": 0,
    "max_uses": null,
    "start_date": "2025-10-15T05:00:00+00:00",
    "end_date": null,
    "status": "ENABLED",
    "schedule": null,
    "can_be_used_with_other_promotions": true,
    "display_name": "Get 10% off on shipping upto $15"
  },
    "meta": {}
  }
```