Skip to main content

Create a Flow trigger

Anchor to RequirementsRequirements

Make sure that you have the following:

  • A test web server that you can use to send information to Shopify Flow. You can use an existing web server. This web server needs to be able to send POST requests to Shopify's GraphQL Admin API.
  • A test app that works with the test web server and can send HTTP requests.
  • A development store that has Shopify Flow and the test app installed.
  • Your application has access to the read_customers scope. The trigger you will build using this tutorial will be using a customer reference which requires that scope.

Anchor to Step 1: Create a Flow trigger extensionStep 1: Create a Flow trigger extension

To give your Flow action a meaningful name, use the following guidelines:

  • Use an object acted on + past tense verb format. For example, Auction bid placed.
  • Use sentence case.
  • Don't use punctuation.
  • Separate words using spaces.

Anchor to Using Shopify CLIUsing Shopify CLI

The following steps show how to create a trigger that sends bid information to Shopify Flow when a bid is placed on an auction.

Use the Shopify CLI to generate a new extension:

  1. Navigate to your app directory.
  2. Run the following command:

Terminal

#!/bin/bash
shopify app generate extension
  1. Select the Flow Trigger as the type of extension.
  2. Provide a meaningful name for your extension.

After you've followed the prompts, Shopify CLI generates the extension's file representation in your app's /extensions directory and gives you a success message. You can then go into your app's /extensions directory and start editing your new extension.

The file structure of your extension should look like the following:

/auction-bid-placed
shopify.extension.toml

To learn more about the extensions file structure, refer to App structure and the documentation for your extension type.

Anchor to Step 2: Customize a Flow trigger configuration fileStep 2: Customize a Flow trigger configuration file

The following procedure requires you to have generated a flow extension using Shopify CLI. In this section you'll use the default trigger template and update it to be a functional extension example.

  1. Change description to Trigger for auction bids.
  2. On the second [[settings.fields]] field, update:
  • type to number_decimal
  • key to Amount

toml

[[extensions]]
name = "Auction Bid Placed"
type = "flow_trigger"
handle = "auction-bid-placed"
description = "Trigger for auction bids."

[settings]

[[settings.fields]]
type = "customer_reference"

[[settings.fields]]
type = "number_decimal"
key = "Amount"

Anchor to Step 3: Enable the draft version of your triggerStep 3: Enable the draft version of your trigger

Running app dev allows changes made to local files to update the draft version of your Flow task extensions. The draft version is only available in your development store.

Note

When app dev is running and "Development store preview" is enabled, the draft version of a task will appear in your development store in place of the deployed version. Other shops will continue to see the deployed version of your task (if one exists). Draft versions can be identified by the "draft" badge. To see the deployed version of the task in your development store, turn off "Development store preview" in the "Extensions" section of your app in Shopify Partners.

  1. Navigate to your app directory.
  2. Run the following command to start using draft versions of your extension(s):
#!/bin/bash
shopify app dev
  1. Follow the prompts.

Anchor to Step 4: Test your triggerStep 4: Test your trigger

After the app dev command has started, you can test the draft version of your trigger in Shopify Flow.

  1. In your development store, create a workflow that uses the trigger that you created for your app.

  2. Using the Admin GraphQL API, send a flowTriggerReceive mutation with the following arguments:

  • The handle of the trigger
  • The payload of the trigger containing the fields defined in the extension TOML
    • The size of the payload (keys included) must be under 50 KB. If the size of the properties body exceeds the limit, then Shopify responds to the GraphQL request with a validation error reading Properties size exceeds the limit of 50000 bytes. As a result, workflows with the specified trigger won't start from this request.

The following is an example of a flowTriggerReceive mutation:

mutation {
flowTriggerReceive(
handle: "auction-bid-placed",
payload: {
"Amount": "30",
"customer_id": 12345
})
{
userErrors {field, message}
}
}
Note

Learn how to authenticate your GraphQL Admin API requests.

The following example shows the same mutation sent in a curl request:

curl --location 'https://{shop_domain}.myshopify.com/admin/api/2025-07/graphql.json' \
--header 'X-Shopify-Access-Token: {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"query": "mutation flowTriggerReceive($handle: String, $payload: JSON) { flowTriggerReceive(handle: $handle, payload: $payload) { userErrors { message field } } }",
"variables": {
"handle": "auction-bid-placed",
"payload": {
"customer_id": {customer_id},
"Amount": 30
}
}
}'

Anchor to Step 5: Deploy your extensionStep 5: Deploy your extension

Note

Deploying extensions using the app deploy command also publishes the extensions. We recommend testing changes by using app dev or deploying to a test app before deploying them to a production app.

Use Shopify CLI to deploy your extensions:

  1. Navigate to your app directory.
  2. Run the following command to start deploying your extension(s):
#!/bin/bash
shopify app deploy
  1. Follow the prompts.

When you receive confirmation that the deploy was successful, your extensions have been released.

Anchor to Next stepsNext steps

Was this page helpful?