Tools reference
The complete surface, in one table. Explanations of what each is for are in the tool guide.
Which of these your assistant can see depends on the connection's access level. A read-only connection is never offered the write tools — they are not registered for it, so there is nothing for it to call.
Reading — 18 tools
Available at every access level.
| Tool | Parameters | Answers |
|---|---|---|
get_setup_health | — | Can the gift widget appear on this store? |
get_campaigns | status? | What offers am I running? |
get_campaign_details | campaignId | How is this one campaign configured? |
get_analytics | days? includeToday? ianaTimezone? | Revenue, orders, conversion, AOV |
check_gift_product | handles | Can this product be given as a gift? |
get_widget_types | — | Which widget types does this store have? |
get_widget_settings | type | How is one widget configured to look? |
get_translations | locale? | What wording do shoppers see? |
get_app_settings | — | The store-wide switches |
get_plan_status | — | Plan, quota, usage |
find_gift_products | query | Which product did the merchant mean, as a gift? |
find_trigger_products | query | Which product did they mean, as a trigger? |
find_collections | query | Which collection did they mean? |
find_customer_segments | query | Which Shopify segment did they mean? |
find_customer_locations | query | Which market or country did they mean? |
find_shipping_rates | query | Which shipping rate did they mean? |
find_markets | — | Which Shopify Markets exist? |
find_pos_locations | query | Which POS location did they mean? |
The eight find_* tools exist so nothing has to be guessed. A merchant says "make the gift the
lavender candle"; the assistant searches, shows what matched, and asks which one if more than one
does. Only a confirmed id is ever passed on.
Writing — 7 tools
Needs read and write access or higher.
| Tool | Parameters | Does |
|---|---|---|
get_campaign_creation_blueprint | type | Reports what this store may configure for one campaign type |
prepare_campaign | campaign | Validates and previews a new campaign. Writes nothing |
add_campaign | campaign confirmationToken | Creates the previewed campaign |
prepare_campaign_edit | campaignId customDiscountEdit? | Rehydrates resources and previews an edit. Writes nothing |
edit_campaign | campaignId + the fields to change | Applies the edit |
set_campaign_status | campaignId status | Turns a campaign on or off |
edit_widget | type fields? translationUpdates? | Changes allowlisted widget settings and wording |
edit_campaign takes around a hundred optional fields covering wording, schedule, thresholds,
gifts, triggers, customer eligibility, delivery, discount economics, usage limits, structured
product settings and translations. Only the fields your campaign type actually renders are accepted;
anything else is refused by name rather than ignored.
Deleting — 2 tools
Needs read, write, and delete access.
| Tool | Parameters | Does |
|---|---|---|
prepare_delete_campaign | campaignId | Previews exactly what deleting would remove. Writes nothing |
delete_campaign | campaignId confirmationToken | Deletes it |
Deletion cannot be undone. The preview names the campaign, its Shopify discounts, and what shoppers
stop seeing; the token it returns is bound to the campaign's configuration at that moment. Change
the campaign in between and the token is refused, so the assistant has to show you the change again.
If you only want to pause an offer, set_campaign_status turns it off and keeps it.
Parameters marked ? are optional; the rest are required.
Prepare, then commit
Create, edit and delete all work the same way, and it is worth knowing why. The first call validates everything and returns a complete preview plus a short-lived confirmation token. The second call carries that token unchanged and is the only one that writes.
| Step | Call | Writes? |
|---|---|---|
| 1 | prepare_campaign / prepare_campaign_edit / prepare_delete_campaign | No |
| 2 | add_campaign / edit_campaign / delete_campaign | Yes |
Repeating the same confirmed call is idempotent — it returns the original result rather than making a second campaign. Changing any commercial field invalidates the token and forces a fresh preview, which is what stops a change being quietly reshaped between the version you approved and the version that was saved.
The same data over REST
Free Gift serves this on two surfaces that share one set of handlers. Whatever a tool returns, its matching endpoint returns — a change to either lands on both.
| Tool | REST endpoint |
|---|---|
get_setup_health | GET /setup-health |
get_campaigns | GET /campaigns |
get_campaign_details | GET /campaigns/{id} |
get_analytics | GET /analytics |
check_gift_product | GET /products |
find_gift_products | GET /gift-products |
find_trigger_products | GET /trigger-products |
find_collections | GET /collections |
find_customer_segments | GET /customer-segments |
find_customer_locations | GET /customer-locations |
find_shipping_rates | GET /shipping-rates |
find_markets | GET /markets |
find_pos_locations | GET /pos-locations |
get_widget_types | GET /widgets |
get_widget_settings | GET /widgets/{type} |
get_translations | GET /translations |
get_app_settings | GET /settings |
get_plan_status | GET /plan |
set_campaign_status | PUT /campaigns/{id}/status |
prepare_campaign | POST /campaigns/preview |
add_campaign | POST /campaigns |
prepare_campaign_edit | POST /campaigns/{id}/edit-preview |
edit_campaign | PATCH /campaigns/{id} |
prepare_delete_campaign | POST /campaigns/{id}/deletion-preview |
delete_campaign | POST /campaigns/{id}/delete |
edit_widget | PATCH /widgets/{type} |
get_campaign_creation_blueprint has no REST equivalent — it describes what an assistant is allowed
to propose, which a script writing its own request body does not need.
The Store API lives at /store-api/v1, takes its own key beginning aov_sk_, and is
meant for scripts and integrations rather than AI clients. Keys are not interchangeable between the
two — see Authentication.
Limits
| Requests | 60 per minute, per connection |
| Result size | 16,000 characters per call |
| Product lookup | 50 handles per call |
| Product search | 10 candidates per query |
| POS locations | Shopify's own 50-location cap, flagged as truncated |
A result that hits the size limit is cut off with a note saying so, and suggesting a narrower request. That note is real information: an assistant that ignores it will summarise a partial answer as though it were complete. Asking for one campaign, one widget type, or one language brings the result back under the limit.
What is deliberately absent
- No customer data. No names, emails, addresses, or individual orders anywhere in the surface.
- No internal identifiers. The store's own record ids and access token are stripped before anything leaves the server.
- No pricing.
get_plan_statusreports your store's plan and usage, never a price list. - No bulk destruction.
delete_campaigntakes one campaign at a time and refuses a token that does not match it. There is no "delete all". - No silent writes. Every write tool that creates, edits or deletes requires a token from a preview you were shown first.