Integrations send a store’s data to services it works with. Automations act on their own when something happens in the store. Both need the integration and automation scopes, which only the Everything set holds (see Scopes).
Integrations
list_integrations (integration:read) lists every integration the store can use, under result. Read the list from there: which integrations exist, and what each takes, is in its answer. Each one has:
id,name,descriptionandkind;enabled: whether it is on;sets_cookies: whether its page tags set cookies in a visitor’s browser, so turning it on shows the storefront’s cookie banner to visitors where the law asks for consent;config_schema: a JSON Schema of its settings, wheresecret: truemarks a secret anddefaultsuggests a value (it is never filled in for you);config: its current settings, without secrets;secret_set: which secrets are set;connection_ended_at: when the connection that set it up ended, or null.
To send a store’s events to an endpoint of your own, add a webhook endpoint with create_webhook instead (see Webhooks).
set_integration (integration:write) takes the integration as { "id": "..." }, a config and enabled:
- Leave
configout to keep the stored settings, for example to only turn it on or off. - A secret left out of
configkeeps its stored value, and a secret set tonullis cleared. - A key
config_schemadoesn’t declare is refused asinvalid, with the reason “not declared”. - A text value is at most 2,000 characters.
- A value the storefront places in the integration’s page tags is read without surrounding spaces, and may hold only letters, digits,
_,+and-(a value in a script’s address also/). Any other is refused asinvalid, with the reason “not usable in its tags”, when you set it or turn the integration on. A secret never goes in a page, so this never applies to one. - Turning one on needs every key its schema requires, or it is
invalidwith the reason “required”. A required key with adefaultstill needs its value inconfig. - For one that sends buyer and order data, turning it on, or changing the settings that say where it sends them (even while it is off), needs the read scopes of the
order.createdwebhook event (see Webhooks). Without them, the call answers HTTP403withinsufficient_scope.
It answers the integration as list_integrations lists it, without its config.
When the connection ends
An integration belongs to a connection. A connection becomes its owner when it sets it up first, when it sends a config other than null, or when it turns it on after the connection that owned it ended. Turning it on or off without a config otherwise leaves the owner as it is. When that connection is revoked, expires or loses the access the integration needs, the integration is turned off and its secrets are dropped, and connection_ended_at says when. To use it again, set its secrets and turn it on with set_integration.
Automations
An automation is a rule: when its trigger happens, it runs its action for the customer it happened to.
| Tool | Scope |
|---|---|
list_all_automations, get_automation, list_automation_runs |
automation:read |
create_automation, update_automation, pause_automation, resume_automation |
automation:write |
delete_automation |
automation:delete |
create_automation takes a trigger, an action and, optionally, a name of up to 200 characters. Each of trigger and action names its kind.
Triggers
product.purchased: a customer buysproduct. Optionally narrowed to one of its prices,price, or to a discount code,discount.product.reviewed: a customer reviewsproduct. Optionally only atmin_ratingor above, from 1 to 5.event.checked_in: a customer is checked in at an event,product. Optionally only at one of its sessions,session, as{ "id": "..." }. See Automations on check-in.
product is { "id": "..." } or { "slug": "..." }. An event.checked_in trigger’s product must be an event, else it’s a conflict on category, and its session one of that event’s. A trigger needs product:read, plus price:read or discount:read when it names a price or a discount.
Actions
product.unlock: gives the customer access toproduct. Needscustomer:writeandproduct:read.price.adjust: makes the customer a single-use discount code, for them alone, offprice. It takesfixed_cents,variable_percent(0 to 100) or both, and optionally awindowwithstarts_atandends_at. Each code made sends adiscounts.unlockedevent. Needsdiscount:writeandprice:read.
Without a scope it needs, the call answers HTTP 403 with insufficient_scope.
{
"name": "Thank-you discount",
"trigger": { "kind": "product.purchased", "product": { "slug": "intro-course" } },
"action": {
"kind": "price.adjust",
"price": { "id": "c41e8b2a-9d07-4f3c-8a65-3b0f7e2d1c94" },
"variable_percent": 20,
"window": { "starts_at": "2026-11-03T00:00:00Z", "ends_at": "2026-12-31T23:59:59Z" }
}
}update_automation changes its name, trigger or action. A new trigger or action needs the scopes creating it would. pause_automation stops it until resume_automation, and delete_automation removes it. Resuming needs the action’s own scope too: customer:write for product.unlock, discount:write for price.adjust. Pausing a paused automation, or resuming a running one, is a conflict with { "field": "status", "current": "paused" } or "running".
A store holds at most 200 automations. Past that, create_automation is a conflict.
Runs
Each time a trigger happens, the automation runs once. A product.reviewed rule runs once per reviewer, and an event.checked_in rule once per customer, whichever session lets them in and however often. list_automation_runs lists runs, filtered by automation_id, status, trigger_kind or occurred_at. A run’s status is:
pending: not run yet.succeeded: done;resultnames what it made, such as the grant or the discount.skipped: nothing to do, withreasonsaying why:paused,rule changed,customer gone,trigger gone,trigger changed,product gone,category unknown,product is repeatable,already entitled,price gone,takes nothing off,window overorunlocks paused.failed: it failed, withreasonset toerror.
Runs are kept for 92 days. Pending runs, and runs of a product.reviewed or event.checked_in trigger that weren’t skipped, are kept past that.
When the connection ends
Automations a connection created keep running after it is revoked, expires or is removed from the business, until they are paused. The Connections page lists what a connection made in each business it reached, under What it made or changed in that business, so you can pause them there. For a connection made before connections could reach several businesses, the API tokens page lists them. An app can also read each automation’s token_id, the token of the connection that created it in that business.
Redirects
The store’s redirects are set up with create_redirect, update_redirect and delete_redirect, listed with list_redirects, and check_path says whether a path is free.
| Tool | Scope |
|---|---|
list_redirects |
site:read |
create_redirect, update_redirect |
site:write |
delete_redirect |
site:delete |
check_path |
site:read, plus the scope of the kind it checks: product:read for product, custompage:read for page, site:read for redirect |
Like an integration, a redirect a connection set up is turned off when that connection ends, with connection_ended_at saying when.