POST /checkout/cart/{cart_id}/discounts

Add a discount to a cart. API Reference: Add Discount to Cart



the ID of the cart you would like to add this SKU to.

Required Body Parameters:


the code (provided by the merchant) of the discount you wish to add to the cart.


the merchant ID the code belongs to.

Discount is only applied when the cart has at least one product from the provided merchant_id.

curl -X POST{cart_id}/discounts \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json" \
-d '{"code": "ABCDE", "merchant_id": 123}'


    "id": 10466,
    "token": "03f8b7b77008401db0ff40eeaac95bc5",
    "user_id": 10002,
    "app_id": 10001,
    "developer_id": 10001,
    "bags": [
            "id": 10455,
            "order_id": 10466,
            "merchant_id": 123,
            "app_id": 10001,
            "status": "IN_PROGRESS",
            "fulfillment_status": "PROCESSING",
            "financial_status": "UNPAID",
            "skus": [
                    "id": 10691,
                    "merchant_id": 123,
                    "app_id": 10001,
                    "product_id": "65677f35d33e4867a90ef0c29683813d",
                    "sku_id": 99603,
                    "external_id": "112::80",
                    "name": "\"Fake Jordan's\" - Black/Black/White",
                    "thumbnail": "",
                    "quantity": 1,
                    "price": 23045,
                    "weight": 69.0,
                    "height": 0.0,
                    "width": 0.0,
                    "length": 0.0,
                    "available": true,
                    "status": "IN_PROGRESS",
                    "product_type": "PHYSICAL",
                    "line_price": 23045
            "taxes": [],
            "sub_total": 23045,
            "taxes_included": false,
            "transactions": [],
            "external_checkout": true,
            "commission_rate": 0.0,
            "date_created": "2023-05-01T15:39:12+0000",
            "remorse_period_ends": "2023-05-31T15:39:12+0000",
            "currency": "USD",
            "external_currency": "USD",
            "channel": "APP",
            "platform": "BIGCOMMERCE",
            "fulfillments": [],
            "discounts": [
                    "id": 10138,
                    "bag_id": 10455,
                    "status": "APPLIED",
                    "type": "CODE",
                    "value_type": "PERCENTAGE",
                    "code": "ABCDE",
                    "external_id": "1",
                    "amount_total": 1152,
                    "date_created": "2023-05-01T15:49:04+0000",
                    "date_last_modified": "2023-05-01T15:49:19+0000"
            "wallet_based_checkout": false,
            "bag_status": "IN_PROGRESS",
            "bag_id": 10455,
            "merchant_name": "Violet BC"
    "sub_total": 23045,
    "status": "IN_PROGRESS",
    "is_guest": true,
    "date_created": "2023-05-01T15:39:11+0000",
    "date_last_modified": "2023-05-01T15:39:11+0000",
    "priced": false,
    "wallet_based_checkout": false,
    "currency": "USD",
    "errors": [],
    "channel": "APP",
    "currency_symbol": "$",
    "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
    "order_status": "IN_PROGRESS",
    "intent_based_checkout": false,
    "order_id": 10466,
    "guest": true

Discount Considerations

When submitting a cart with discounts, only APPLIED discounts are considered, all other discount statuses will be cleaned from cart.

Discount statuses:

  • PENDING - Discount added to cart, but not applied to merchant platform yet
  • APPLIED - Discount added to cart, validated and applied to merchant platform
  • INVALID - Invalid discount in merchant platform, check order errors for details
  • NOT_SUPPORTED - Platform currently not supported
  • ERROR - Unexpected error applying discount, check order errors for details
  • EXPIRED - Discount previously applied that is no longer valid in the merchant platform

Current supported platforms:

  • BigCommerce
  • Magento
  • WooCommerce
  • Shopify (beta)

Using Discount Codes in Shopify

The Shopify Draft Orders API does not support discount codes by default. This limitation required us to integrate more deeply with Shopify and utilized other resources from the Shopify API to recreate their discounting engine. While most discount codes are now supported there are still a few scenarios we have not yet added support for. Support for these will come in the next release of this discounting engine.

Unsupported Shopify Discount Configurations

  • Collection ID Requirements
  • Customer ID Requirements
  • Customer Group Requirements
  • Country Requirements
  • Buy X Get Y

If a discount code with any of these requirements is entered the discount object will be returned with a status of NOT_SUPPORTED and an order error will be generated with a message indicating that the discount code configuration was too complex.

Was this page helpful?