Call cartDiscountCodesUpdate with the cart ID and a discountCodes array of strings representing the codes to apply.
Read cart.discountCodes in the response to check the applicable field on each code—a code may be syntactically accepted but not applicable to current cart contents.
Inspect cart.cost.totalAmount vs cart.cost.subtotalAmount to surface the discount amount to the buyer.
To remove all discount codes, pass an empty array to cartDiscountCodesUpdate.
Handle userErrors for codes that are completely invalid or expired at the time of the call.
Note that automatic discounts are applied server-side without needing a code; manual codes and automatic discounts may interact—consult current Shopify docs for stacking rules.
Known gotchas
A discount code can have applicable: false without being in userErrors, meaning the code exists but does not apply to the current cart contents or customer; always check the applicable field.
Discount stacking and combination rules (e.g., whether a percentage and a free-shipping code can combine) are configured in Shopify admin and enforced server-side; do not assume stacking is allowed.
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