Set up a campaign
Describing an offer in a sentence and having it exist is the thing write access is for. It takes four steps, and only the last one writes anything.
Ask: "Set up a free gift: spend over $80 and get the lavender candle free."
Needs: a connection with read and write access. On a read-only connection the assistant will say so and stop — raise the level, then restart your client.
Step 1 — Find out what this store may configure
get_campaign_creation_blueprint with the campaign type. It reports required merchant intent,
supported options, localized defaults, limits and any policy blockers for this store — a Shopify
Plus feature or a paid-plan gate is knowable here rather than at the moment of saving.
Nothing is reserved and nothing is created.
Step 2 — Turn names into ids
The store was described in words, so every Shopify resource has to be resolved before it can be
used: find_gift_products for the candle, find_trigger_products or find_collections for
whatever triggers the offer, and find_customer_segments, find_customer_locations,
find_markets, find_shipping_rates or find_pos_locations for anything else the campaign needs.
If more than one product matches, your assistant should ask which one you meant, not pick. Two similar names and a silent choice is how the wrong product ends up being given away for free. The result carries variant titles and giftability precisely so the choice can be made properly.
The finders also report blockers: a gift that is out of stock, unpublished, a draft, or
subscription-only is flagged now rather than discovered by a shopper later.
Step 3 — Prepare, and actually read the preview
prepare_campaign takes the whole intended campaign. It validates it against the blueprint,
re-reads the resources from Shopify, applies safe defaults, checks your plan, your discount code and
your schedule — and returns a complete preview plus a short-lived confirmation token.
It writes nothing. Not to Shopify, not to the app.
This preview is the thing to read properly. It is the last point at which a misunderstanding is free:
- the threshold, the gift and the quantity
- how the gift is delivered — automatic, popup, floating button, slide cart
- the Shopify discount code it will create
- whether it stacks with other discounts
- the schedule, and whether it starts immediately
- any warnings — these are part of the answer, not decoration
Step 4 — Confirm
add_campaign, with the campaign unchanged and the token from the preview. This is the call that
creates the campaign and starts or schedules a live Shopify discount.
| Repeating the same confirmed call | Returns the campaign already made — never a duplicate |
| Changing any commercial field | Invalidates the token; a new preview has to be shown first |
| Letting the token expire | Nothing happens. Prepare again |
Storefront sync usually takes up to a minute. A campaign that exists in the admin but has not yet appeared on the storefront is normal in the first minute, not a fault.
Afterwards
| You want to | Use |
|---|---|
| Pause it | set_campaign_status |
| Change wording, threshold, gifts, schedule | prepare_campaign_edit then edit_campaign |
| Check it can actually appear | get_setup_health |
| Remove it for good | prepare_delete_campaign then delete_campaign — needs delete access, cannot be undone |
What you finish holding
A live campaign you approved in full before it existed, and a conversation that still contains the preview it was created from.