Shopify Flow triggers
A trigger is a workflow component in Shopify Flow. It represents an event that starts a workflow, and can be something that happens in a store or in an app. You can connect your app to Shopify Flow so that events that occur in your app can trigger workflows.
This guide shows you how to add a trigger to your app to define the properties that your app will send to Shopify Flow.
Requirements
Anchor link to section titled "Requirements"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 Flow.
- A test app that works with the test web server.
- A development store that has Shopify Flow and the test app installed.
Considerations
Anchor link to section titled "Considerations"- When you create a trigger, the payload that you send to Shopify Flow needs to be less than 1 MB and contain specific content in the body.
- Triggers have the same API rate limits as the Shopify API.
- To view and test your Shopify Flow trigger in the Shopify Flow editor, you must publish the extension (or its changes) in the Partner Dashboard. Currently, draft tasks are not supported.
Shopify properties
Anchor link to section titled "Shopify properties"When you create a trigger, you add the properties that your trigger sends to Shopify Flow. You can add a custom property or a predefined Shopify property.
A Shopify property lets you send the identifier of a Shopify resource to Shopify Flow. Merchants can then use data from that resource in their conditions and actions. You can add one of each Shopify property to a trigger:
Shopify property type | Description |
---|---|
customer_id | The numeric ID of the customer, such as customer or legacyResourceId . Your app must have the read_customers scope. |
order_id | The numeric ID of the order, such as order or legacyResourceId . Your app must have the read_orders scope. |
product_id | The numeric ID of the product, such as product or legacyResourceId . Your app must have the read_products scope. |
For example, your trigger sends a customer ID to Shopify Flow. The merchant can create a condition that checks the customer's total spend amount. In their action, the merchant can include the template variables for customers (such as {{customer.email}}
).
1. Add a trigger
Anchor link to section titled "1. Add a trigger"The following steps show how to create a trigger that sends weather information to Shopify Flow when the temperature in a city changes.
- In your Partner Dashboard, open the Shopify Flow app extension:
- Click Apps and then open your test app.
- Click Extensions and then click Create extension.
- Under Flow, click the Flow/Triggers card.
- Enter an internal extension name for your trigger and click Save.
- On the extension's overview page, click Open draft to edit the details of the extension.
- Enter a title and description for the trigger that will be shown to merchants. For example:
Field | Content to enter |
---|---|
Trigger title | Weather changes |
Trigger description | Trigger when the weather changes |
Copy the GraphQL endpoint (
https://{shop}.myshopify.com/admin/api/2023-01/graphql.json
) that displays under the Trigger description field to a text file.Your app uses this endpoint to send your POST request to Shopify Flow.
Click Add property, choose a data type, and create the properties that display in Shopify Flow when your merchant chooses your trigger.
For example, create two properties that contain the following values.
Property 1 - Data type: Short Text
- Field name: City location
- Label: City where the weather changed
Property 2 - Data type: Number
- Field name: Temperature
- Label: Temperature in Fahrenheit (rounded to the nearest whole number)
Click Create version and choose minor or major version.
To see and test the extension (and changes) in the Flow app, you next need to Publish the extension draft.
How properties are surfaced in Shopify Flow
Anchor link to section titled "How properties are surfaced in Shopify Flow"Properties display in Shopify Flow as conditions that your merchants can use when they use your trigger.
Shopify Flow also uses these properties to create corresponding Liquid template variables for your merchants to use in workflow actions. When it creates template variables for these properties, Shopify Flow condenses the property names by removing spaces and changing the case of the first letter in each word. For example, {customerEmail}
.
Property names
Anchor link to section titled "Property names"Property names need to be self-describing and readable. Use sentence case and separate words with spaces (not underscores or hyphens). These names can contain only alphabetical characters (a-z, A-Z) and spaces.
When you refer to these properties in the payload that you send to Shopify Flow, enter these names (do not use shortened versions). For example, { properties: { "City location": string } }
.
2. Configure your web server
Anchor link to section titled "2. Configure your web server"In your web server, add the functionality that posts an HTTP request to Shopify Flow, and then use the flowTriggerReceive
mutation. The POST request needs to be less than 1 MB and must contain the following content in its body:
- the ID of the trigger
- the property information that you defined when you created the trigger for your app
- the access token for your merchant’s store
- a hash-based message authentication (HMAC) header that uses the client secret associated with your app
the name and URL of the resource involved in the event that sends the trigger information to Shopify Flow.
These details display in the logs in Shopify Flow so that you and the merchant can use them when troubleshooting. For example, a request that is involved in triggering a weather change could have the following resource:
The POST request needs to use the GraphQL endpoint https://{shop}.myshopify.com/admin/api/2023-01/graphql.json
, where {shop}
refers to the store that has a workflow that uses your trigger and 2023-01
refers to the current stable api version. The URL is the same one that was displayed in the Partner Dashboard when you created your trigger.
The following is an example of a POST body:
3. Test the trigger
Anchor link to section titled "3. Test the trigger"After you've created a trigger in the Partner Dashboard and added support for it in your web server, you can test the trigger in Shopify Flow.
In your development store, create a workflow that uses the trigger that you created for your app.
In your web server, run the event that sends the trigger information to Shopify Flow.
In a test environment, you can run the following command to send the trigger information to your test store. When Shopify Flow receives the POST request from your app, any workflow that contains your trigger will start.
- 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 webhooks from Shopify Flow about the stores that are using your triggers in enabled workflows.