Flow trigger API
Start your Shopify Flow workflows from your own server with the Shopwaive HTTP POST trigger and the Flow trigger API (2026-11)
POST /api/trigger starts every Shopify Flow workflow in your store that begins with the Shopwaive HTTP POST trigger. Use it when your CRM or your server should decide in Flow what happens next, for example a deposit with the Shopwaive Increment balance action.
Send your Shopwaive API key in the X-Shopwaive-Access-Token header. The key needs Change balances through the REST API (wallets:write). Send an Idempotency-Key header with every request: see Retry safely. This request does not need the X-Shopwaive-Platform header.
Base URL: https://app.shopwaive.com
Starts every Shopify Flow workflow in your store that begins with the Shopwaive HTTP POST trigger. The fields you send become the trigger's variables in Flow. Every field is optional.
This request does not need the X-Shopwaive-Platform header.
Send an Idempotency-Key header with a new value for each request. The same key again gets the first answer and does not start the workflows again. Without the header, a request made with a Shopwaive API key returns 400 idempotency_key_required and starts nothing.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
Required with a Shopwaive API key. A key you choose for this request: 1 to 255 printable ASCII characters, with no space at either end. A UUID is a good choice. Use a new key for each request, and send the same key again to retry: Shopwaive answers with the first answer and does not start the workflows again. Without it, the request returns 400 idempotency_key_required and starts nothing.
3f9c2b8e-1d4a-4c7e-9b2f-6a1e5d0c7b3aEvery field is optional. Each one becomes the HTTP POST trigger's variable of the same name in Shopify Flow.
The customer's email address.
A Shopify customer id.
A Shopify order id.
A Shopify product id.
An order line id.
A collection id, or several separated by commas.
Where the request comes from, for example a URL.
Any reference from your CRM or server.
Always reaches Flow as true: a false value is dropped and the default true is sent. For a true or false condition, use enabled.
trueA number for your workflow's conditions. 0 if you leave it out.
0A date as text, for example an ISO date. The time of the request if you leave it out.
For reference only. Changes no balance.
For reference only. Changes no balance.
For reference only. Changes no balance.
A Shopify customer segment query, for a Shopwaive action later in the workflow.
A note or title for a Shopwaive action later in the workflow.
An expiry date as text, for example 2028-04-25.
A media link for a Shopwaive action later in the workflow.
An email address for a later action such as Send email.
A recipient's name for a later action.
An email template name for a later Shopwaive email action.
A true or false value for your workflow. false if you leave it out.
falseAny text for your workflow.
A number for your workflow. 0 if you leave it out.
0Any text for your workflow, for example a referral code.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
Any text for your workflow.
The trigger was queued for Shopify Flow. The body is an empty object.
The Idempotency-Key header is missing (a request made with a Shopwaive API key needs one) or is not valid. Nothing was changed.
The API key was not accepted. A value that starts with swak_ gets status failed and a message that names the reason. A key of a store that uninstalled Shopwaive is paused, not revoked: it gets reason app_uninstalled and works again when the app is reinstalled. No key, or a token Shopwaive does not know, gets unknown_api_token.
The API key cannot change balances. A request that changes a balance or starts a workflow needs a key with Change balances through the REST API (wallets:write), chosen when the key is created. Nothing was changed. Reading balances needs no scope.
A request with the same key is still running. Retry after the seconds in Retry-After.
This Idempotency-Key was already used with different fields. Nothing was changed.
The key could not be checked, or the outcome of the request is not known yet. Retry the same request, with the same Idempotency-Key, after the seconds in Retry-After. Shopwaive checks its ledger before it acts on it again.
POST /api/trigger HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 118
{
"email": "customer@example.com",
"reference": "crm-12345",
"authorized": true,
"number": 10,
"note": "Signed up at the event"
}{}Request body
Every field is optional. Each one becomes the trigger's variable of the same name in Flow.
text
The customer's email address
customerid
text
A Shopify customer id
orderid
text
A Shopify order id
productid
text
A Shopify product id
lineitemid
text
An order line id
collectionid
text
A collection id, or several separated by commas
source
text
Where the request comes from, for example a URL
reference
text
Any reference from your CRM or server
authorized
true or false
Always reaches Flow as true: a false value is dropped. For a true or false condition, use enabled.
number
number
For your workflow's conditions. 0 if you leave it out.
date
text
A date, for example an ISO date. The time of the request if you leave it out.
previous, transaction, available
number
For reference in Flow only. They change no balance.
segment
text
A Shopify customer segment query, for a Shopwaive action later in the workflow
note
text
A note or title for a Shopwaive action later in the workflow
expiration
text
An expiry date, for example 2028-04-25
media
text
A media link for a Shopwaive action later in the workflow
recipient, recipientname
text
An email address and a name for a later action such as Send email
template
text
An email template name for a later Shopwaive email action
enabled
true or false
For your workflow. false if you leave it out.
points
number
For your workflow. 0 if you leave it out.
event, referral, type, variant, limit, version, style, title, group, gid
text
Any text for your workflow
Send each field as the type in the table. Flow reads the variables with these types.
Answer
HTTP 200 with an empty object {} means the trigger was queued for Shopify Flow. Your workflows then run in Shopify Flow.
Retry safely
Send an Idempotency-Key header with every request: 1 to 255 printable ASCII characters with no space at either end, a new value for each request (a UUID is a good choice). The same key again gets the first answer, with Idempotent-Replayed: true, and does not start the workflows again. To start the workflows twice on purpose, send each request with its own key. A request made with a Shopwaive API key and no Idempotency-Key returns HTTP 400 with the reason idempotency_key_required, and starts nothing.
To set up the workflow in Shopify Flow, see Shopify Flow in the Help Center.
Last updated