To create a basic percentage or fixed-amount discount code, call the `discountCodeBasicCreate` mutation with a `basicCodeDiscount` input specifying `title`, `codes` (array with `code` string), `customerGets` (value and items), `startsAt`, and optionally `endsAt` and `usageLimit`.
For buy-X-get-Y promotions, use `discountCodeBxgyCreate` instead, configuring `customerBuys` and `customerGets` inputs accordingly.
For free shipping discounts, use `discountCodeFreeShippingCreate` with destination and minimum requirements.
After creation, check the mutation response's `codeDiscountNode.id` for the new discount's GID and inspect `userErrors` for validation failures.
To deactivate a discount code, call `discountCodeDeactivate` with the discount's GID.
To retrieve existing discount codes, query `codeDiscountNodes` with filters on `query` (e.g., by code string or status).
Known gotchas
Discount codes are case-insensitive at checkout but are stored as entered — duplicate-check logic should normalize case before creation to avoid confusing near-duplicates.
The `usageLimit` applies to the total number of times the code can be used across all customers; per-customer limits are set separately via `appliesOncePerCustomer`.
Automatic discounts (using `discountAutomaticBasicCreate`) do not require a code and apply at checkout without customer input — mixing automatic and code discounts on the same order follows Shopify's combining rules which must be explicitly configured.
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