Skip to main content
POST
/
store
/
carts
/
{id}
/
promotions
curl -X POST 'http://localhost:9000/store/carts/cart_01JB2KB1CD/promotions' \
  -H 'Content-Type: application/json' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
  -d '{"promo_codes": ["SUMMER10"]}'

{
  "cart": {
    "id": "cart_01JB2KB1CD",
    "promotions": [
      {
        "id": "promo_01JB2KD5JK",
        "code": "SUMMER10",
        "is_automatic": false,
        "application_method": { "type": "percentage", "value": 10, "currency_code": "eur" }
      }
    ],
    "items": [
      {
        "id": "cali_01JB2KB3EF",
        "quantity": 1,
        "unit_price": 4500,
        "adjustments": [
          { "id": "caadj_01JB2KD6LM", "code": "SUMMER10", "promotion_id": "promo_01JB2KD5JK", "amount": 450 }
        ]
      }
    ],
    "discount_total": 450,
    "total": 4950
  }
}
Applies promotion codes through Mercur’s seller-aware workflow so seller-scoped promotions only adjust that seller’s items; sending an empty array replaces (clears) the applied codes.

​
Path parameters

​
id
string
required
The cart’s ID.

​
Query parameters

​
fields
string
Comma-separated fields and relations to include on the returned cart; prefix with +/- to add to or remove from the defaults.

​
Body parameters

​
promo_codes
string[]
required
Promotion codes to add; an empty array removes all applied codes.

​
Response

​
cart
object
curl -X POST 'http://localhost:9000/store/carts/cart_01JB2KB1CD/promotions' \
  -H 'Content-Type: application/json' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
  -d '{"promo_codes": ["SUMMER10"]}'

{
  "cart": {
    "id": "cart_01JB2KB1CD",
    "promotions": [
      {
        "id": "promo_01JB2KD5JK",
        "code": "SUMMER10",
        "is_automatic": false,
        "application_method": { "type": "percentage", "value": 10, "currency_code": "eur" }
      }
    ],
    "items": [
      {
        "id": "cali_01JB2KB3EF",
        "quantity": 1,
        "unit_price": 4500,
        "adjustments": [
          { "id": "caadj_01JB2KD6LM", "code": "SUMMER10", "promotion_id": "promo_01JB2KD5JK", "amount": 450 }
        ]
      }
    ],
    "discount_total": 450,
    "total": 4950
  }
}