Call the cartDiscountCodesUpdate Storefront API mutation with the cartId and a discountCodes array (strings) to apply one or more discount codes to the cart; replacing the array removes any previously applied codes
In the mutation response query cart.discountCodes { code applicable } to confirm which codes were recognized; applicable: false means the code exists but does not apply to the current cart (wrong conditions, expired, etc.)
Query cart.lines { nodes { discountAllocations { discountedAmount { amount currencyCode } } } } to see per-line discount amounts allocated from code-based discounts
Query cart.cost { totalAmount subtotalAmount totalTaxAmount } to see the net cart totals after discounts; compare subtotalAmount before and after applying a code to confirm the discount is reflected
To remove all discount codes, call cartDiscountCodesUpdate with an empty discountCodes array
If a code is applicable: false and you need to diagnose why, check the discount's conditions (minimum purchase, specific products, usage limit reached, customer eligibility) via Admin GraphQL discountNode query
Known gotchas
cartDiscountCodesUpdate replaces the entire discount codes list — if you want to add a second code, pass both the existing code and the new code in the discountCodes array; passing only the new code removes the first
The Storefront API only shows whether a code is applicable but not the reason it is not applicable — you need Admin GraphQL or merchant UI to debug condition failures; build a helpful UI message that encourages customers to check code terms
Function-backed automatic discounts do not appear in discountCodes — they appear only in discountAllocations; do not confuse the two when building discount display UI
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp