> For the complete documentation index, see [llms.txt](https://api.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.shopwaive.com/classic/reference/rest-api-documentation/shopify-flow.md).

# Shopify Flow

Start your Shopify Flow workflows from your own server with the Shopwaive HTTP POST trigger

`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)** or **Start Shopify Flow from another store (flow:trigger)**. Send an `Idempotency-Key` header with every request: see [Retry safely](#retry-safely). This request does not need the `X-Shopwaive-Platform` header.

Base URL: `https://app.shopwaive.com`

## Start your Shopify Flow workflows

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Shopify Flow","description":"Start the store's Shopify Flow workflows that begin with the Shopwaive HTTP POST trigger."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"parameters":{"TriggerIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"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.\n","schema":{"type":"string","minLength":1,"maxLength":255}}},"schemas":{"TriggerRequest":{"description":"Every field is optional. Each one becomes the HTTP POST trigger's variable of the same name in Shopify Flow.","type":"object","properties":{"email":{"description":"The customer's email address.","type":"string"},"customerid":{"description":"A Shopify customer id.","type":"string"},"orderid":{"description":"A Shopify order id.","type":"string"},"productid":{"description":"A Shopify product id.","type":"string"},"lineitemid":{"description":"An order line id.","type":"string"},"collectionid":{"description":"A collection id, or several separated by commas.","type":"string"},"source":{"description":"Where the request comes from, for example a URL.","type":"string"},"reference":{"description":"Any reference from your CRM or server.","type":"string"},"authorized":{"description":"Always reaches Flow as `true`: a `false` value is dropped and the default `true` is sent. For a true or false condition, use `enabled`.","type":"boolean","default":true},"number":{"description":"A number for your workflow's conditions. 0 if you leave it out.","type":"number","default":0},"date":{"description":"A date as text, for example an ISO date. The time of the request if you leave it out.","type":"string"},"previous":{"description":"For reference only. Changes no balance.","type":"number"},"transaction":{"description":"For reference only. Changes no balance.","type":"number"},"available":{"description":"For reference only. Changes no balance.","type":"number"},"segment":{"description":"A Shopify customer segment query, for a Shopwaive action later in the workflow.","type":"string"},"note":{"description":"A note or title for a Shopwaive action later in the workflow.","type":"string"},"expiration":{"description":"An expiry date as text, for example `2028-04-25`.","type":"string"},"media":{"description":"A media link for a Shopwaive action later in the workflow.","type":"string"},"recipient":{"description":"An email address for a later action such as Send email.","type":"string"},"recipientname":{"description":"A recipient's name for a later action.","type":"string"},"template":{"description":"An email template name for a later Shopwaive email action.","type":"string"},"enabled":{"description":"A true or false value for your workflow. `false` if you leave it out.","type":"boolean","default":false},"event":{"description":"Any text for your workflow.","type":"string"},"points":{"description":"A number for your workflow. 0 if you leave it out.","type":"number","default":0},"referral":{"description":"Any text for your workflow, for example a referral code.","type":"string"},"type":{"description":"Any text for your workflow.","type":"string"},"variant":{"description":"Any text for your workflow.","type":"string"},"limit":{"description":"Any text for your workflow.","type":"string"},"version":{"description":"Any text for your workflow.","type":"string"},"style":{"description":"Any text for your workflow.","type":"string"},"title":{"description":"Any text for your workflow.","type":"string"},"group":{"description":"Any text for your workflow.","type":"string"},"gid":{"description":"Any text for your workflow.","type":"string"}}},"IdempotencyKeyMissing":{"description":"A request made with a Shopwaive API key, or a deposit to a customer segment, was sent without an Idempotency-Key header.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"idempotency_key_required"},"header":{"type":"string","const":"Idempotency-Key"},"message":{"type":"string"}}},"IdempotencyRefused":{"type":"object","properties":{"status":{"type":"string","enum":["IDEMPOTENCY_KEY_INVALID","IDEMPOTENCY_CONCURRENT_REQUEST","IDEMPOTENCY_KEY_PARAMETER_MISMATCH"]},"message":{"type":"string"}}},"KeyRefused":{"description":"A value that starts with swak_ was not accepted.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"description":"Set only for a paused key (app_uninstalled: HTTP 401; the store uninstalled Shopwaive, and the key works again when the app is reinstalled) and for a key without the scope the request needs (missing_scope: HTTP 403).","type":"string","enum":["app_uninstalled","missing_scope"]},"scope":{"description":"With missing_scope. The scope the request needs: wallets:write, flow:trigger on POST /api/trigger, or wallets:read for a read by a key with flow:trigger and no wallets: scope.","type":"string"},"message":{"description":"Without reason: Invalid X-Shopwaive-Access-Token: followed by the reason: not-a-shopwaive-api-key, key-not-recognised, key-revoked or store-has-no-token. With reason: a sentence that says what to do.","type":"string"}}},"UnknownToken":{"description":"No key was sent, or Shopwaive does not know the token.","type":"object","properties":{"error":{"type":"string","const":"unknown_api_token"},"message":{"type":"string"}}},"IdempotencyPending":{"type":"object","properties":{"status":{"type":"string","const":"pending"},"code":{"type":"string","enum":["IDEMPOTENCY_OUTCOME_PENDING","IDEMPOTENCY_STORE_UNAVAILABLE"]},"message":{"type":"string"}}},"TemporarilyUnavailable":{"type":"object","properties":{"status":{"type":"string","const":"failed_temporary"},"message":{"type":"string"}}},"KeyCheckUnavailable":{"description":"A swak_ key could not be checked just now.","type":"object","properties":{"status":{"type":"string","const":"failed"},"message":{"type":"string","const":"Shopwaive API key lookup is temporarily unavailable. Retry."}}}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"IdempotentReplayed":{"description":"`true` when this is the recorded answer to an earlier request with the same key or content. Nothing was changed again.","schema":{"type":"string","enum":["true"]}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"responses":{"IdempotencyKeyMissingOrInvalid":{"description":"The Idempotency-Key header is missing (a request made with a Shopwaive API key needs one) or is not valid. Nothing was changed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyKeyMissing"},{"$ref":"#/components/schemas/IdempotencyRefused"}]}}}},"Unauthorized":{"description":"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`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KeyRefused"},{"$ref":"#/components/schemas/UnknownToken"}]}}}},"KeyMissingScope":{"description":"The API key does not hold the scope this request needs, and `scope` names it. A request that changes a balance needs **Change balances through the REST API (wallets:write)**. `POST /api/trigger` needs `wallets:write` or **Start Shopify Flow from another store (flow:trigger)**: a key with neither is refused with `scope` `flow:trigger`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRefused"}}}},"IdempotencyBusy":{"description":"A request with the same key is still running. Retry after the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}},"IdempotencyMismatch":{"description":"This Idempotency-Key was already used with different fields. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}},"RetryLater":{"description":"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.\n","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyPending"},{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"}]}}}}}},"paths":{"/api/trigger":{"post":{"tags":["Shopify Flow"],"operationId":"sendFlowTrigger","summary":"Start your Shopify Flow workflows","description":"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.\n\nThis request does not need the X-Shopwaive-Platform header.\n\nSend 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.\n","parameters":[{"$ref":"#/components/parameters/TriggerIdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerRequest"}}}},"responses":{"200":{"description":"The trigger was queued for Shopify Flow. The body is an empty object.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyMissingOrInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/KeyMissingScope"},"409":{"$ref":"#/components/responses/IdempotencyBusy"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"503":{"$ref":"#/components/responses/RetryLater"}}}}}}
```

## Request body

Every field is optional. Each one becomes the trigger's variable of the same name in Flow.

| key                                                                      | type          | value                                                                                                    |
| ------------------------------------------------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------- |
| email                                                                    | 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.

A request made with a key that has **Start Shopify Flow from another store (flow:trigger)** reaches Flow with `source` set to `shopwaive-key`.

## 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](https://docs.shopwaive.com/shopify/shopify-flow) in the Help Center.
