Use the discountAutomaticBxgyCreate mutation with a DiscountAutomaticBxgyInput specifying title, startsAt, customerBuys (value type ALL_QUANTITY or specific quantity, and items as product/variant IDs), and customerGets (value as percentage or free, and items)
For customerBuys.items use a DiscountProducts input with productIds and productVariantIds; similarly for customerGets.items; both support collections via a DiscountCollections input
Set usesPerOrderLimit to cap how many times a single order can trigger the BXGY logic; omitting it allows unlimited stacking within one order
Confirm discountClass defaults to PRODUCT for BXGY; set combinesWith if you want this discount to stack with other discount classes
Query the returned automaticDiscount node including status, startsAt, endsAt, and customerGets to verify the mutation succeeded
Test by adding the qualifying buy items to a cart and querying cartLines with discountAllocations to confirm the get items receive their discount
Known gotchas
productVariantIds in the items input must reference variants that actually belong to the specified productIds, or the mutation returns a validation error; double-check GID formats
BXGY discounts apply to the cheapest eligible get items first by default; if you need a different behavior, a custom Function with cart.lines.discounts.generate.run gives you full control
If both buy and get items overlap (a product is in both lists), Shopify may behave unexpectedly — test this combination explicitly before deploying to production
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