Create a price rule via POST /admin/api/2024-01/price_rules.json with value_type (percentage or fixed_amount), value (negative number for discount), target_type (line_item or shipping_line), allocation_method, and starts_at/ends_at datetime strings for the sale window
Optionally scope the price rule to specific products, variants, or collections using entitled_product_ids, entitled_variant_ids, or entitled_collection_ids arrays
Create a discount code under the price rule via POST /admin/api/2024-01/price_rules/{price_rule_id}/discount_codes.json with a code string; this code is what customers enter at checkout
For automatic discounts (no code required), use the GraphQL discountAutomaticBasicCreate mutation instead, specifying startsAt, endsAt, and minimumRequirement
To run a time-limited sale on specific variant prices without discount codes, use the compare_at_price field on variants and update variant prices directly for the sale period, reverting them after ends_at
Monitor active price rules via GET /admin/api/2024-01/price_rules.json?starts_at_min=...&ends_at_max=... to audit overlapping promotions that could stack unintentionally
Known gotchas
Price rules created via the REST API and automatic discounts created via GraphQL are separate systems and can stack; test all combinations in a development store to verify the checkout total
Shopify does not automatically deactivate price rules at ends_at; the rule becomes ineligible but remains in the system — clean up expired rules periodically to avoid confusion
Percentage discounts are applied to the line item price at the time of checkout, not the listed compare_at_price; ensure your sale framing is accurate to avoid customer disputes
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