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

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

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 the entire resource in their conditions and actions. You can add one of each Shopify property to a trigger:

Shopify property typeDescription
customer_idThe globally unique ID of the customer. Your app must have the read_customers scope.
order_idThe globally unique ID of the order. Your app must have the read_orders scope.
product_idThe globally unique ID of the product. 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

The following steps show how to create a trigger that sends weather information to Shopify Flow when the temperature in a city changes.

  1. In your Partner Dashboard, open the Shopify Flow app extension:
    1. Click Apps and then open your test app.
    2. Click Extensions and then click Flow.
  2. Click Add trigger, and enter a title and description for your trigger. For example:
    FieldContent to enter
    Trigger title Weather changes
    Trigger description Trigger when the weather changes
  3. Copy the GraphQL endpoint (https://{shop}.myshopify.com/admin/api/2021-07/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.

  4. 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)

  5. Click Save.

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

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

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 API secret key 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/2021-07/graphql.json, where {shop} refers to the store that has a workflow that uses your trigger and 2021-07 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

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.

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

  2. 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.

Next 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 webhooks from Shopify Flow about the stores that are using your triggers in enabled workflows.