POST
/
v1
/
carts
/
:id
/
coupons
curl --location --request POST 'https://api.stateset.com/v1/carts/cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/coupons' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "code": "WELCOME10"
}'

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "cart",
  "customer_id": "cust_abc123",
  "status": "active",
  "items": [
    {
      "id": "ci_abc123",
      "product_id": "prod_123",
      "quantity": 3,
      "unit_price": 9999,
      "subtotal": 29997,
      "discounts": [
        {
          "promotion_id": "promo_welcome10",
          "code": "WELCOME10",
          "amount": 2999,
          "type": "percentage"
        }
      ],
      "final_price": 26997
    },
    {
      "id": "ci_ghi789",
      "product_id": "prod_789",
      "quantity": 1,
      "unit_price": 2499,
      "subtotal": 2499,
      "discounts": [
        {
          "promotion_id": "promo_welcome10",
          "code": "WELCOME10",
          "amount": 250,
          "type": "percentage"
        }
      ],
      "final_price": 2249
    }
  ],
  "subtotal": 32496,
  "discount_amount": 3249,
  "tax_amount": 2268,
  "shipping_amount": 599,
  "total": 32114,
  "applied_coupons": [
    {
      "code": "WELCOME10",
      "promotion_id": "promo_welcome10",
      "promotion_name": "Welcome 10% Off",
      "discount_amount": 3249,
      "applied_at": "2024-06-20T16:30:00Z"
    }
  ],
  "messages": [
    {
      "type": "success",
      "message": "Coupon applied successfully. You saved $32.49!"
    }
  ]
}
This endpoint applies a coupon code to the cart. The system validates the coupon and calculates applicable discounts based on cart contents and customer eligibility.

​
Authentication

This endpoint requires a valid API key with carts:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The unique identifier of the cart

​
Request Body

​
code
string
required
Coupon or promotion code to apply
​
validate_only
boolean
default:"false"
Only validate without applying (preview discount)

​
Response

Returns the updated cart with applied discount. 
curl --location --request POST 'https://api.stateset.com/v1/carts/cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/coupons' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "code": "WELCOME10"
}'

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "cart",
  "customer_id": "cust_abc123",
  "status": "active",
  "items": [
    {
      "id": "ci_abc123",
      "product_id": "prod_123",
      "quantity": 3,
      "unit_price": 9999,
      "subtotal": 29997,
      "discounts": [
        {
          "promotion_id": "promo_welcome10",
          "code": "WELCOME10",
          "amount": 2999,
          "type": "percentage"
        }
      ],
      "final_price": 26997
    },
    {
      "id": "ci_ghi789",
      "product_id": "prod_789",
      "quantity": 1,
      "unit_price": 2499,
      "subtotal": 2499,
      "discounts": [
        {
          "promotion_id": "promo_welcome10",
          "code": "WELCOME10",
          "amount": 250,
          "type": "percentage"
        }
      ],
      "final_price": 2249
    }
  ],
  "subtotal": 32496,
  "discount_amount": 3249,
  "tax_amount": 2268,
  "shipping_amount": 599,
  "total": 32114,
  "applied_coupons": [
    {
      "code": "WELCOME10",
      "promotion_id": "promo_welcome10",
      "promotion_name": "Welcome 10% Off",
      "discount_amount": 3249,
      "applied_at": "2024-06-20T16:30:00Z"
    }
  ],
  "messages": [
    {
      "type": "success",
      "message": "Coupon applied successfully. You saved $32.49!"
    }
  ]
}