Create a marketing automation action
An action is a marketing activity that's executed in a store or in an app when certain conditions are met. You can connect your app to Shopify marketing automations so that your app receives data when a workflow action runs.
When your marketing automation action is triggered, you need to send information about the marketing activity, as well as engagement data, back to Shopify. This data is displayed to merchants in the Marketing area of the Shopify admin so merchants can understand ther impact of their marketing automations.
This tutorial shows you how to add an action to your app so that merchants can use it in their marketing automations, and set up your app to send engagement data back to Shopify. For example, you might create an action that sends an SMS message to a customer.
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account
- You've created a development store.
- You've set up a test web server that you can use to send requests to and receive requests from Shopify marketing automations.
- You've created an app and installed it on your development store. The test app needs to work with the test web server.
Step 1: Configure your web server
Anchor link to section titled "Step 1: Configure your web server"To use marketing automation actions, you need a web server that can listen for requests that are sent when an action is run, created, or deleted.
You need to add the following endpoints to your server:
| Endpoint | Description |
|---|---|
| An action execution endpoint | The endpoint where the automation tool sends your action's payload. The payload contains data that you can use to execute the action in your app. |
| A marketing activity create endpoint | This endpoint is called when a step in a workflow is created using the action. Shopify creates a marketing activity and sends the marketing_activity_id to you.In response, your app needs to send details about the marketing activity back to Shopify, including UTM parameters. These UTM parameters are required so that sessions and sales can be attributed to the marketing activity. |
| A marketing activity delete endpoint | This endpoint is called when a workflow associated with the marketing activity is deleted. When you receive a request at this endpoint, you can stop sending marketing engagement data, and clean up any data related to the marketing activity. All workflow runs associated with this marketing activity will be canceled, and the marketing activity will be hidden from merchants. |
To learn more about the endpoint requirements for your server, refer to Action endpoints.
Verifying requests
Anchor link to section titled "Verifying requests"For security reasons, make sure that you verify the following elements in each request:
- The POST request's HMAC header (Either
x-shopify-hmac-sha256orhttp-x-shopify-hmac-sha256). The HMAC header should be verified before you process the payload. For more information, refer to Verifying requests. - The payload
action_definition_id. This ID should match the ID of the action that you created, and can be retrieved from the payload preview.
Step 2: Create a Flow action extension
Anchor link to section titled "Step 2: Create a Flow action extension"To create an action that merchants can use in their Shopify marketing automation workflows, you need to create a Flow/Actions extension to your app.
Create the action extension and a draft version
Anchor link to section titled "Create the action extension and a draft version"- In your Partner Dashboard, click Apps.
- Click the app that you want to add your Shopify marketing automation action to.
- Click Extensions, then click Create or Create extension.
- Under the Flow tab, click Flow/Actions.
- In the Extension name field, name your action. This name is used only for internal purposes.
- In the Working draft card, click Open draft to draft a new version of your action.
- Enter a title and description for the action. In the Action Preview area, you can see how the title and action will appear to merchants when they're choosing actions in Shopify marketing automation.
- Enter the URL for the action execution endpoint that you created. Shopify marketing automation will send the action's JSON payload to this endpoint when it's about to execute your action.
Configure the payload schema
Anchor link to section titled "Configure the payload schema"Under Payload schema, select and configure the data that will be sent to your app when the action is triggered.
You can include two types of properties in your payload schema: Shopify properties and merchant-configurable properties.
Your payload schema must contain the Marketing activity ID Shopify property. If you don't include this property, then the action won't be available to Shopify marketing automations.
In the Payload preview area, you can preview the data model that Shopify marketing automations will use as the JSON payload that it sends to your web server.
Shopify properties
Anchor link to section titled "Shopify properties"Properties are Shopify resources that can be used by your action. The ID for the resource is usually populated by a workflow trigger. For example, if a workflow is triggered by a customer abandoning their cart, then that customer's ID is populated in the workflow execution environment.
Select This property is required if the property must be present in the environment to use the action.
For example, if you're creating a Send marketing SMS action, then you can specify that the action needs the Customer property. When the action is executed, Shopify passes the customer_id in the payload. You can then use the ID to query for the customer phone number and SMS marketing consent before sending the SMS.
| Shopify property type | Description |
|---|---|
Customer (customer_id) |
The id of the customer. Your app must have the read_customers scope. |
Order (order_id) |
The id of the order. Your app must have the read_orders scope. |
Product (product_id) |
The id of the product. Your app must have the read_products scope. |
Marketing activity ID (marketing_activity_id) |
Endpoints for Shopify to call when a workflow using the action is created. |
Marketing activity ID
Anchor link to section titled "Marketing activity ID"To allow your Flow action to be used in Shopify marketing automations, you need to configure the Marketing activity ID Shopify property.
Under Payload schema, click Add property, and then select Marketing activity ID.
The marketing activity ID property requires two URLs. Each represents a marketing activity endpoint that you created on your server.
| URL | Description | Endpoint |
|---|---|---|
| Marketing activity creation URL | This endpoint is called when a step in a workflow is created using the action. Shopify creates a marketing activity and sends the marketing_activity_id to you.In response, your app needs to send details about the marketing activity back to Shopify, including UTM parameters. These UTM parameters are required so that sessions and sales can be attributed to the marketing activity. |
Marketing activity create |
| Marketing activity deletion URL | This endpoint is called when a workflow associated with the marketing activity is deleted. When you receive a request at this endpoint, you can stop sending marketing engagement data, and clean up any data related to the marketing activity. All workflow runs associated with this marketing activity will be canceled, and the marketing activity will be hidden from merchants. |
Marketing activity delete |
Merchant-configurable properties
Anchor link to section titled "Merchant-configurable properties"Merchant-configurable properties are fields for merchants to populate as a part of the action configuration. For example, if you're creating an action called Send marketing SMS, then you might want to let the merchant provide the body text of the SMS message.
When the action is executed, the merchant-configured values are passed as a part of the action payload.
Step 3: Send marketing data and insights back to Shopify
Anchor link to section titled "Step 3: Send marketing data and insights back to Shopify"When a merchant uses your action in a workflow, you need to send information back to Shopify using the GraphQL Admin API. You need to send information to Shopify at the following stages:
| Stage | Action |
|---|---|
| After the marketing activity is created | Update marketing activity metadata, including the marketing activity title and status. |
| When an action run is completed | Send engagement metrics. This data appears on the following marketing automation reports:
|
Update marketing activity metadata
Anchor link to section titled "Update marketing activity metadata"When a merchant creates a step in a workflow that uses your action, Shopify creates a marketing activity and notifies your app by sending a request to your app's marketing activity create endpoint. After you send a response acknowledging the request, you need to send an asynchronous marketingActivityUpdate request. The request must include the following:
| Attribute | Description |
|---|---|
id |
The ID of the marketing activity that you received in the marketing activity create request payload. |
title |
The title of the marketing activity. This title is displayed in the Marketing section of the Shopify admin. You should set this title to something related to the action configuration, so the merchant can identify the marketing activity in relation to the marketing automation. For example, if the action sends an email, then you might set the title of the marketing activity to the email subject line. |
status |
The status of the marketing activity. Status values have additional meanings in the context of marketing automations:
|
Send engagement metrics
Anchor link to section titled "Send engagement metrics"After each workflow run is executed, your app needs to send engagement metrics back to Shopify using the marketingEngagementCreate mutation. Engagement metrics include impressions, likes, shares, and clicks.
This data appears on the following marketing automation reports:
- The summary page for the marketing automation
- The marketing activity report
You can send metrics as a daily aggregate, or as an all-time aggregate using the isCumulative flag.
Step 4: Test the action and data updates
Anchor link to section titled "Step 4: Test the action and data updates"After you've created an action in the Partner Dashboard and added support for it in your web server, you can test the action in Shopify marketing automations on your development store.
In your development store, create a Shopify marketing automations workflow that uses the action. For example, create a custom automation workflow that starts with a Shopify trigger such as Customer abandons checkout, and then add this action to the workflow.
Trigger the workflow using the trigger you selected. For example, if you selected the Customer abandons checkout trigger, create a checkout in the development store and leave without completing it.
When the workflow completes, the action payload is sent to your web server, and a request to create a marketing activity is sent to the marketing activity create endpoint.
In the Marketing page, in the Recent marketing activities section, make sure that your marketing activity appears in the list with a unique name.
In the Recent marketing activities section, beside your marketing activity, click the menu button
⋯and then click View report. Ensure that any engagement metrics that should be updated by the action run are reflected in the report. It might take up to 30 minutes for updates to be reflected in the report.