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.
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:
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.
- Change description to
Trigger for auction bids.
- On the second
[[settings.fields]]
field, update:
type
tonumber_decimal
key
toAmount
toml
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.
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.
- Navigate to your app directory.
- Run the following command to start using draft versions of your extension(s):
- 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.
-
In your development store, create a workflow that uses the trigger that you created for your app.
-
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 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
The following is an example of a flowTriggerReceive
mutation:
The following example shows the same mutation sent in a curl request:
Anchor to Step 5: Deploy your extensionStep 5: Deploy your extension
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:
- Navigate to your app directory.
- Run the following command to start deploying your extension(s):
- Follow the prompts.
When you receive confirmation that the deploy was successful, your extensions have been released.
Anchor to Next stepsNext steps
- Familiarize yourself with Shopify Flow and learn about building connectors.
- Connect your app to Shopify Flow so that your app receives data and information when a workflow action runs.
- Learn how to receive lifecycle events from Shopify Flow about the stores that are using your triggers in enabled workflows.
- Learn how to use complex data types in your Shopify Flow trigger.