Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Promotions
  4. Clear Promo Codes

Clear Promo Codes

DELETE https://api.firmly.work/api/v2/domains/{domain}/cart/promo-codes

Removes promotional codes from the cart. The merchant determines what cleared state looks like (typically coupons: [], cart_discount reset, line-item discounts removed) and returns the updated cart.

​​ Authentication

  • x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

  • domain (string, required) — The merchant’s domain (e.g. staging.luma.gift).

​​ Request Body

No request body.

​​ Response

Returns the full cart (same schema as Get Cart) with promotions cleared.

​​ Examples 


curl -X DELETE https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes \
  -H "x-firmly-authorization: YOUR_TOKEN"


const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes', {
  method: 'DELETE',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }

});



const cart = await response.json();


import requests


response = requests.delete(
    'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes',
    headers={'x-firmly-authorization': 'YOUR_TOKEN'}

)


cart = response.json()

​​ Response Example 


{
  "cart_id": "a5600193-2c13-3356-d063-711da63b7cd7",
  "platform_id": "example_commerce",
  "shop_id": "staging.luma.gift",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "c62279b9-3a72-0bbd-1377-be0033ad23dd",
      "sku": "WT08-XS-Purple",
      "description": "Antonia Racer Tank",
      "quantity": 2,
      "price": { "currency": "USD", "value": 49.99, "number": 4999, "symbol": "$" },
      "line_price": { "currency": "USD", "value": 99.98, "number": 9998, "symbol": "$" },
      "msrp": { "currency": "USD", "value": 59.99, "number": 5999, "symbol": "$" },
      "image": { "url": "https://staging.luma.gift/antonia-racer-tank.jpg", "alt": "Antonia Racer Tank", "type": "default" }
    }
  ],
  "coupons": [],
  "sub_total": { "currency": "USD", "value": 99.98, "number": 9998, "symbol": "$" },
  "cart_discount": { "currency": "USD", "value": 0, "number": 0, "symbol": "$" },
  "shipping_total": { "currency": "USD", "value": 9.99, "number": 999, "symbol": "$" },
  "tax_total": { "currency": "USD", "value": 8.80, "number": 880, "symbol": "$" },
  "fees": [{ "description": "Recycle fee", "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" }],
  "fee_total": { "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" },
  "total": { "currency": "USD", "value": 120.77, "number": 12077, "symbol": "$" },
  "schema_version": "2.0"

}

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

400 — MissingAuthHeader

The x-firmly-authorization header is missing or empty.


{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }
400 — InvalidToken

The authorization token is not a valid JWT structure.


{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }
400 — InvalidAPIToken

The API token (server-to-server secret) is invalid or has been revoked.


{ "code": 400, "error": "InvalidAPIToken", "description": "API token is invalid." }
400 — BadRequest

Server-to-server auth was attempted but required headers are missing or malformed.


{ "code": 400, "error": "BadRequest", "description": "Bad request." }
401 — Unauthorized

The authorization token was rejected.


{ "code": 401, "error": "Unauthorized", "description": "Unauthorized." }
401 — InvalidJWTToken

The device JWT signature does not verify, or required claims are missing.


{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }
404 — PartnerNotFound

The appid claim on the device JWT does not map to a known partner / tenant.


{ "code": 404, "error": "PartnerNotFound", "description": "Partner not found." }
404 — DomainNotFound

The {domain} path parameter does not match any merchant configured with Firmly, or the merchant has been disabled.


{ "code": 404, "error": "DomainNotFound", "description": "This domain was not found in firmly servers." }
404 — CartNotFound

No cart exists for this device on this domain.


{ "code": 404, "error": "CartNotFound", "description": "Cart was not found." }
409 — ClearPromoCodeNotAllowed

The merchant’s configuration disables API-driven promo-code clearing for this store.


{ "code": 409, "error": "ClearPromoCodeNotAllowed", "description": "Clear promo code is not allowed." }
412 — OperationNotSupported

The merchant’s platform does not support clearing promo codes via API.


{ "code": 412, "error": "OperationNotSupported", "description": "This operation is not supported for this store." }