Starting a workflow by HTTP request

Starting workflows that begin with a custom trigger can be done by sending an HTTP request to the Flow Companion app.

Authorization

You can authorize the request in one of two ways:

1. Provide the token in the Authorization header.
2. Provide the token in the JSON body as bearerToken.

The Authorization header has priority. If the header is missing, the server will look for bearerToken in the request body. If both are missing, the request is unauthorized.

Header example:

Authorization: bearer {token}

Body example:

{
  "bearerToken": "{token}",
  ...
}

You can create a bearer token for authorization on the application page in the Settings → Manage authentication tokens section.

Request bodies

Below are the URLs and request bodies for each type of event. All additional parameters are optional.

Custom trigger

POST https://flow-companion.mivicle.app/rest/1/flow/start

{
  "specifier": "Specifier to use in a workflow condition",
  "additionalParameters": {
    "stringParameter": "some string parameter",
    "numberParameter": 0,
    "booleanParameter": true
  }
}

Order: custom trigger

POST https://flow-companion.mivicle.app/rest/1/flow/start/order

{
  "itemId": "ID (207119551) or legacyResourceId (gid://shopify/Order/207119551) of the order",
  "specifier": "Specifier to use in a workflow condition",
  "additionalParameters": {
    "stringParameter": "some string parameter",
    "numberParameter": 0,
    "booleanParameter": true
  }
}

Customer: custom trigger

POST https://flow-companion.mivicle.app/rest/1/flow/start/customer

{
  "itemId": "ID (207119551) or legacyResourceId (gid://shopify/Customer/207119551) of the customer",
  "specifier": "Specifier to use in a workflow condition",
  "additionalParameters": {
    "stringParameter": "some string parameter",
    "numberParameter": 0,
    "booleanParameter": true
  }
}

Product: custom trigger

POST https://flow-companion.mivicle.app/rest/1/flow/start/product

{
  "itemId": "ID (207119551) or legacyResourceId (gid://shopify/Product/207119551) of the product",
  "specifier": "Specifier to use in a workflow condition",
  "additionalParameters": {
    "stringParameter": "some string parameter",
    "numberParameter": 0,
    "booleanParameter": true
  }
}

Response Codes

• 200 OK - Workflow started successfully.
• 400 Bad Request - Error in the request parameters.
• 400 Bad Request - Failed to start the workflow. The response body will contain a list of errors received from Shopify Flow.
• 412 Precondition Failed - No active workflow matches the trigger conditions for this HTTP request.
• 429 Too Many Requests - Too many requests have been made in a short period. Retry the request later.
• 500 Internal Server Error - An unknown error occurred.

See also:

• Сustom workflow trigger