Skip to main content
Builds a discount and returns a link to review it in the AIOD editor. Works for anything AIOD can do: a BOGO, a free gift with purchase, tiered or volume quantity breaks, a fixed bundle price, free shipping over a spend threshold, a percentage or amount off a product or collection, a scheduled seasonal sale. The same call proposes changes to an existing discount when you pass targetDiscountId — raising a threshold, extending an end date, swapping the gift, re-shaping a tier ladder.
Nothing is created in Shopify. No discount exists and no shopper can receive one until the merchant opens the returned link and saves it there. Say so when you report back — a staged draft is not a live discount.
Tool name: shopify_discount_draft · Previously: save_discount_draft · Writes nothing to Shopify

​
When to use it

This is the default. Because it touches nothing, it covers building an offer all the way up to the moment the merchant looks at it. Create in test mode is the tool that makes a real discount, and it only applies once the merchant has actually asked for that.

​
Parameters

​
About config

Shapes come from Read the discount schema and are checked strictly. Creating needs a template id. Editing needs only the fields that change — they’re merged onto the stored configuration, not swapped in for it, which is why you should read the discount first.

​
What comes back

​
When it works

Give the merchant url exactly as it comes — it’s a direct link into the AIOD editor in their Shopify admin. The config comes back enriched with product titles and thumbnails, so it reads the way the editor will render it.

​
When it’s rejected

The rejection contains its own fix. Depending on what failed it carries either schemaReference (the template’s contract) or fieldSyntaxReference (exact condition and reward syntax) — one or the other, never both, to stay within the response budget. Use it instead of fetching the schema again. The rejection codes are listed on the tools overview.

​
What it checks before staging

Every draft goes through the same gate, in order:
  1. Shape repair. Common near-misses — object-wrapped conditions, string operators — are fixed automatically before anything is validated.
  2. Field policy. For an edit, the saved discount’s template decides which fields you may change, not the one you sent. Anything outside that allowlist is dropped.
  3. No-op check. A patch that merges back to an identical rule is rejected — it means the change you meant to make wasn’t actually in there.
  4. Empty tier check. A tier left with nothing meaningful in it is rejected rather than staged silently.
  5. Validation and cart simulation. Errors or a failed simulation reject the draft. Warnings alone don’t.

​
Things people ask that land here

  • “Set up 20% off the Summer collection for July.”
  • “Draft a buy 2 get 1 free on t-shirts so I can look at it.”
  • “Raise the free-shipping threshold on my existing offer from 50to50 to 75.”
  • “Extend the Black Friday discount through Cyber Monday.”

​
Getting it right

  • Always say the draft isn’t live and that the merchant has to open the link and save.
  • Fix only what the rejection names. Don’t rewrite the whole configuration.
  • Never retry a template_field_out_of_scope rejection with the same fields. That setting genuinely isn’t editable for that template — say so instead.
  • Put the merchant’s own words in userMessage, not a paraphrase of your plan. It’s stored and shown back to them.