Starting a workflow by HTTP request

Starting workflows that begin with a custom trigger can be done by sending an HTTP request to the Workflow 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 → Triggers → Custom triggers → REST API 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
  }
}

Company: custom trigger

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

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

Metaobject: custom trigger

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

{
  "itemId": "GID (gid://shopify/Metaobject/1234567890) or numeric ID (1234567890) of the metaobject",
  "specifier": "Specifier to use in a workflow condition",
  "additionalParameters": {
    "stringParameter": "some string parameter",
    "numberParameter": 0,
    "booleanParameter": true
  }
}

If the metaobject doesn't exist — including private (app-owned) metaobjects of other apps — the request fails with 400 Bad Request.

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.
• 401 Unauthorized - The API token is missing or unknown.
• 402 Payment Required - The app subscription is required to start a custom workflow.
• 412 Precondition Failed - No active workflow matches the trigger conditions for this HTTP request.
• 429 Too Many Requests - Your store's Shopify API capacity is used up for the moment. Retry the request after the number of seconds the Retry-After header names.
• 500 Internal Server Error - An unknown error occurred.

An error response is JSON with a message and a requestId. Quote the requestId when you contact support: it leads straight to what happened to that request.

See also:

• Сustom workflow trigger