Add Discount to Checkout

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": [],
    "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 a discount to an existing checkout.

Use this endpoint to apply the following discounts:

Apply a manual discount to a cart. In this case, you can distribute the discount between each line item in the cart based on the item value.
Apply a manual discount against a specific line item.
Apply a manual discount at the item-level with a cart-level discount.

Notes:

When you call this API, you clear out all existing discounts applied to line items, including product and order-based discounts.
You cannot apply a manual discount to a specific line item if you have already applied a coupon or automatic promotion to it.

Required Fields:

discounted_amount at the cart-level or at the item-level

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.

Adds a discount to an existing checkout. Use this endpoint to apply the following discounts: * Apply a manual discount to a cart. In this case, you can distribute the discount between each line item in the cart based on the item value. * Apply a manual discount against a specific line item. * Apply a manual discount at the item-level with a cart-level discount. Notes: * When you call this API, you clear out all existing discounts applied to line items, including product and order-based discounts. * You cannot apply a manual discount to a specific line item if you have already applied a coupon or automatic promotion to it. Required Fields: * `discounted_amount` at the cart-level or at the item-level 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.

Request

This endpoint expects an object.

cartobjectOptional

Response

dataobject

metaobject

Response metadata.

Errors

409

Conflict Error

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Request

Response

Errors

OAuth scopes

Authentication header

Further reading