Add Discount to Checkout

POST

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

POST

/stores/:store_hash/v3/checkouts/:checkoutId/discounts

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/checkouts/checkoutId/discounts \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "cart": {
    "discounts": [
      {
        "discounted_amount": 10
      }
    ]
  },
  "version": 1
}'

{
  "data": {
    "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
    "cart": {
      "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
      "customer_id": 11,
      "email": "janedoe@example.com",
      "currency": {
        "code": "USD"
      },
      "tax_included": false,
      "base_amount": 31.95,
      "channel_id": 1,
      "discount_amount": 0,
      "cart_amount_inc_tax": 33.23,
      "cart_amount_ex_tax": 31.95,
      "coupons": [],
      "discounts": [
        {
          "id": "8edef915-8e8e-4ebd-bece-31fbb1191a7e",
          "discounted_amount": 13.6
        }
      ],
      "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": [
              {
                "id": 18,
                "discounted_amount": 13.6
              },
              {
                "id": 49,
                "discounted_amount": 2.4
              },
              {
                "id": "manual-discount",
                "discounted_amount": 10
              }
            ],
            "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,
            "comparison_price": 33.23,
            "extended_comparison_price": 33.23,
            "is_require_shipping": true,
            "is_mutable": 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",
      "manual_discount_amount": 10
    },
    "billing_address": {},
    "consignments": [],
    "taxes": [
      {
        "name": "Tax",
        "amount": 1.28
      }
    ],
    "coupons": [],
    "fees": [],
    "order_id": null,
    "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": "",
    "staff_note": " "
  },
  "meta": {}
}

Adds or replaces manual discounts on an existing checkout.

Each request sets the checkout’s complete manual-discount state. The request is not additive: manual discounts from an earlier request that you omit from the new payload are removed. This endpoint does not remove coupons or automatic promotions.

Use the request body to apply:

An order-level manual discount with cart.discounts[].discounted_amount. BigCommerce distributes the discount across line items based on each item’s value.
An item-level manual discount with cart.line_items[].id and cart.line_items[].discounted_amount.
Order-level and item-level manual discounts together by including both arrays in the same request.

Manual discounts interact with coupons and automatic promotions as follows:

Manual discount level	Coupon or automatic promotion level	Behavior
Order	Order or item	The discounts stack. The result is fully additive and does not depend on which discount is applied first.
Item	Order or item	The discounts are mutually exclusive, and the first-applied discount remains. A conflicting manual-discount request is rejected, a coupon request returns a `422` response, and an automatic promotion does not apply.

If an item-level manual discount is already applied, adding a coupon returns a 422 response with the message “Coupon {coupon_code} cannot be applied in combination with item level manual discount.” An eligible automatic promotion does not apply while an item-level manual discount exists.

The required field is discounted_amount at the order level, item level, or both.

To prevent lost updates from concurrent requests, include the optional version field in the request payload. If the provided version does not match the server’s cart version, the API returns a conflict error.

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.

cartobjectOptional

The complete manual-discount state to apply to the checkout.

Response

dataobjectOptional

metaobjectOptional

Response metadata.

Errors

409

Conflict Error