Add Coupon to Checkout

POST

https://api.bigcommerce.com/stores/:store_hash/v3/checkouts/:checkoutId/coupons

POST

/stores/:store_hash/v3/checkouts/:checkoutId/coupons

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/checkouts/checkoutId/coupons \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "data": {
    "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
    "cart": {
      "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
      "customer_id": 11,
      "email": "janedoe@example.com",
      "currency": {
        "code": "USD"
      },
      "base_amount": 31.95,
      "channel_id": 1,
      "discount_amount": 0,
      "cart_amount_inc_tax": 33.23,
      "cart_amount_ex_tax": 31.95,
      "coupons": [
        {
          "code": "SHOP20",
          "id": 1,
          "coupon_type": "percentage_discount",
          "discounted_amount": 0.9,
          "display_name": "20% Off"
        }
      ],
      "discounts": [
        {
          "id": "8edef915-8e8e-4ebd-bece-31fbb1191a7e",
          "discounted_amount": 0
        }
      ],
      "line_items": {
        "physical_items": [
          {
            "quantity": 1,
            "id": "8edef915-8e8e-4ebd-bece-31fbb1191a7e",
            "variant_id": 359,
            "product_id": 188,
            "sku": "DUST1",
            "name": "Hello",
            "url": "https://{store_hash}/all/dustpan-brush/",
            "is_taxable": true,
            "image_url": "https://cdn11.bigcommerce.com/s-{store_hash}/products/188/images/460/dustpan1_1024x1024_1024x1024__43447__69128.1534344539.330.500.jpg?c=2",
            "discounts": [],
            "discount_amount": 0,
            "coupon_amount": 0,
            "original_price": 35.95,
            "list_price": 31.95,
            "sale_price": 33.23,
            "extended_list_price": 31.95,
            "extended_sale_price": 33.23,
            "is_require_shipping": true,
            "parent_id": 123,
            "gift_wrapping": {},
            "coupons": []
          }
        ],
        "digital_items": [],
        "gift_certificates": [],
        "custom_items": []
      },
      "created_time": "2019-08-05T15:38:14+00:00",
      "updated_time": "2019-08-05T15:41:28+00:00"
    },
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "janedoe@example.com",
      "company": "BigCommerce",
      "address1": "123 Main Street",
      "address2": "Apt 1",
      "city": "Austin",
      "state_or_province": "",
      "state_or_province_code": "",
      "country_code": "",
      "postal_code": "",
      "phone": "12125685555",
      "custom_fields": [],
      "id": "5d484d668e5aa",
      "country": ""
    },
    "consignments": [
      {
        "id": "5d484e28d20a8",
        "address": {
          "email": "jane2@example.com",
          "country_code": "US",
          "first_name": "BigCommerce",
          "last_name": "Cart/Checkout",
          "company": "",
          "address1": "123 Main Street",
          "address2": "",
          "city": "Austin",
          "state_or_province": "Texas",
          "state_or_province_code": "TX",
          "postal_code": "78751",
          "phone": "688546",
          "country": "United States",
          "customFields": [
            {
              "field_id": "field_25",
              "field_value": "Great!"
            }
          ]
        },
        "available_shipping_options": [
          {
            "description": "Ship by Weight",
            "id": "006a58a98c9a844225552ee2a9c60ca8",
            "type": "shipping_byweight",
            "image_url": "",
            "cost": 8,
            "transit_time": "",
            "additional_description": ""
          },
          {
            "description": "Flat Rate",
            "id": "722d78b5120de60a725e41be9bb8d999",
            "type": "shipping_flatrate",
            "image_url": "",
            "cost": 12,
            "transit_time": "",
            "additional_description": ""
          },
          {
            "description": "UPS® (UPS Next Day Air®)",
            "id": "71090fa93c8985348892543c3f4887b6",
            "type": "shipping_upsready",
            "image_url": "",
            "cost": 43.9,
            "transit_time": "1 business day",
            "additional_description": ""
          }
        ],
        "coupon_discounts": [],
        "discounts": [],
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "line_item_ids": [
          "8edef915-8e8e-4ebd-bece-31fbb1191a7e"
        ]
      }
    ],
    "taxes": [
      {
        "name": "Tax",
        "amount": 1.28
      }
    ],
    "coupons": [
      {
        "code": "SHOP20",
        "id": 1,
        "coupon_type": "percentage_discount",
        "display_name": "20% Off",
        "discounted_amount": 0.9
      }
    ],
    "shipping_cost_total_inc_tax": 0,
    "shipping_cost_total_ex_tax": 0,
    "handling_cost_total_inc_tax": 0,
    "handling_cost_total_ex_tax": 0,
    "tax_total": 1.28,
    "subtotal_inc_tax": 33.23,
    "subtotal_ex_tax": 31.95,
    "grand_total": 33.23,
    "created_time": "2019-08-05T15:38:14+00:00",
    "updated_time": "2019-08-05T15:41:28+00:00",
    "customer_message": ""
  },
  "meta": {}
}

Adds a coupon code to a checkout.

You can use multiple coupons by using this endpoint to apply one coupon at a time on your storefront. Ensure you enable the Promotion Settings in your control panel to allow for multiple coupons per order.

You cannot add a coupon when an item-level manual discount is already applied. The API returns a 422 response with the message “Coupon {coupon_code} cannot be applied in combination with item level manual discount.”

Required Fields

coupon_code

Limits

Coupon codes have a 50-character limit.

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Checkouts	modify	`store_checkouts`
Checkouts	read-only	`store_checkouts_read_only`
Checkout Content	modify	`store_checkout_content`
Checkout Content	read-only	`store_checkout_content_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

checkoutIdstringRequired

ID of the checkout; the same as the cart ID.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects an object.

coupon_codestringOptional

Coupon codes have a 50-character limit.

versionintegerOptional

The cart version that you expect to apply the updates. If the provided version doesn’t match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.

Response

dataobjectOptional

metaobjectOptional

Response metadata.

Errors

409

Conflict Error

422

Unprocessable Entity Error