Skip to content

Set a cart's promotion codes

PUT
/commerce/delivery/v1/carts/{id}/promotion-codes
curl --request PUT \
--url https://api.ebitex.io/commerce/delivery/v1/carts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/promotion-codes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "codes": [ "example" ] }'

Replaces the cart’s promotion codes with { "codes": ["SPRING"] } (at most 10, each at most 64 characters). The codes are recorded and returned, and change no price in this release. Returns the whole cart.

A cart belongs to one shopper in one store and holds SKUs and quantities only: it never holds a price, because the server prices everything, so a client cannot name one. The shopper is proven by their visitor token, sent in X-Visitor-Token: a missing, expired, revoked or unrecognised token is 401 visitor_token_required. Another shopper’s cart, and a cart in another store, answer 404 cart_not_found. The key must carry the checkout permission (Allow carts and checkout when the key is made); a key that can only read answers 403 scope_denied. Cart responses are never cached (Cache-Control: private, no-store).

The cart is returned as { id, currency, deliveryAddress, billingAddress, promotionCodes, lines, shipping, totals, updatedUtc }. Each line is { sku, productKey, name, options, quantity, unit, amount, availability, available, issue, taxPercent, taxName, converted }: unit and amount are money in the cart’s currency (amountMinor, currency, amount, as elsewhere), availability is a status as in the catalogue, available is present only when the key may see counts (as for stock), and issue is unavailable or unpriced on a line that no longer sells and contributes nothing to the totals. converted is true when the price was converted from the store’s own currency rather than set for this one. shipping is { status, name, amount } with status of not_needed (nothing in the cart ships), needs_address, unavailable (the store cannot ship there in this currency: such a cart is refused at checkout, never shipped free) or ok. totals is { pricesIncludeTax, taxCalculated, items, net, tax, total }: tax is worked out from where the order goes (the delivery address for shipped goods, the billing address otherwise), and until there is an address, or when the store has no rate for it, taxCalculated is false and tax is absent, not zero. net and tax are present only when tax is calculated; total is always present for a store whose prices include tax, and only once tax is calculated for one whose prices do not.

Key: commerce.checkout.write

id
required
string format: uuid
Media typeapplication/json
One of:
null
Examplegenerated
{
"codes": [
"example"
]
}

OK

invalid_promotion_codes: at most 10 codes of at most 64 characters.

visitor_token_required: send the shopper’s visitor token in X-Visitor-Token.

missing_api_key or invalid_api_key: no key was sent, or it is unknown, revoked or expired, or its store binding was removed.

payment_required: the organization’s subscription needs attention.

scope_denied: the key was not allowed to run carts and checkout.

scope_denied: the key lacks commerce.delivery.read. app_not_available: Commerce is not enabled for the organization. origin_denied or ip_denied: the key was used from an origin or address outside its restrictions.

cart_not_found: there is no such cart for this shopper in this store.

concurrency_conflict: another request changed the cart; read it and retry.

rate_limited: slow down; Retry-After says how long to wait.

rate_limited: the key spent its requests-per-minute budget; Retry-After says how long to wait. too_many_failed_authentications: too many bad keys from this address.