Create a marketing automation action

Anchor to RequirementsRequirements

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

Anchor to Step 1: Configure your web serverStep 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.

Optionally, you can also add the following:

• an endpoint to validate actions
• a custom configuration page, and an endpoint that lets users preview your custom configuration page

Add the following endpoints to your server:

To learn more about the endpoint requirements for your server, refer to Action endpoints.

To learn how to create a custom configuration page, refer to Build a custom configuration page.

Anchor to Verifying requestsVerifying 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-sha256 or http-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.

Anchor to Step 2: Create a Flow action extensionStep 2: Create a Flow action extension

To create an action that users can use in their Shopify marketing automation workflows, you need to add a Flow/Actions extension to your app. Optionally, you can add a custom configuration page to display in the Shopify Flow editor, and add an endpoint to perform custom validation.

Anchor to Create the action extension and a draft versionCreate the action extension and a draft version

For the action creation please refer to the Flow documentation.

Anchor to Configure the payload schemaConfigure 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.

Anchor to Shopify propertiesShopify 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.

Anchor to Marketing activity IDMarketing 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.

Anchor to Abandonment IDAbandonment ID

An abandonment object represents a customer's online store session that ends after browsing products, after adding a product to the cart, or during checkout, without completing a purchase. Depending on how far the customer made it in their journey, the object might contain metadata on the products that were viewed, the products that were added to cart, and the details of the checkout.

An abandonment object is present in workflows using the Customer left online store without making a purchase and Customer abandons checkout triggers. If there is no abandonment in the workflow, then Shopify Flow passes a NULL value for this field. If your action isn't intended to be used only in abandonment workflows, then you don't need to select This property is required.

Anchor to Merchant-configurable propertiesMerchant-configurable properties

Merchant-configurable properties are fields for users 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 user provide the body text of the SMS message.

When the action is executed, the user-configured values are passed as a part of the action payload.

Anchor to Optional: Add a custom configuration pageOptional: Add a custom configuration page

To give merchants a more seamless action configuration experience, and to enable them to manage resources that are external to Shopify marketing automations, you can embed a page from your app in the Shopify marketing automations editor. Building a custom configuration page requires creating and hosting an App Bridge-enabled page as a part of your app, which can then be surfaced to merchants Shopify marketing automations. Learn how to build a custom configuration page.

A custom configuration page also requires a custom configuration page preview endpoint that provides text and images that describe the custom configuration page to merchants.

If you built a custom configuration page that you want to display to merchants in the Shopify Flow editor, then you need to provide details about where to access the page and preview data for the page.

1. Under Custom configuration page, select Enable a custom configuration page for this action.
2. In the Destination URL field, enter the URL for the custom configuration page that you created.
3. In the Preview URL field, enter the URL for your custom configuration page preview endpoint.

Anchor to Optional: Configure custom validationOptional: Configure custom validation

If you want to perform custom validation on the contents of the properties that you define as a part of your payload schema, then you can expose an endpoint where Shopify marketing automations will send the properties and the values that the merchant sets on save.

If you configured a custom configuration page for your action, then this endpoint is required.

1. Under Custom validation, select Enable custom validation for this action. If you enabled a custom configuration page, then this option is automatically selected.
2. In the Validation endpoint field, enter the URL for the custom validation endpoint that you created.

Anchor to Step 3: Send marketing data and insights back to ShopifyStep 3: Send marketing data and insights back to Shopify

When a user 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:

Anchor to Update marketing activity metadataUpdate marketing activity metadata

When a user 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:

Anchor to Send engagement metricsSend 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.

Anchor to Send a marketing activity delivery status for an abandonment objectSend a marketing activity delivery status for an abandonment object

After each workflow run is executed, your app needs to check if the workflow contains an abandonment ID. If it does, you need to send the marketing activity delivery status for the abandonment object to Shopify using the abandonmentUpdateActivitiesDeliveryStatuses mutation. This data will be used by workflow conditions. If the abandonment is of type CHECKOUT, it also appears on the abandoned checkout details page, in the Recovery automation results section. You need to provide the following information:

• The abandonment ID
• The marketing activity ID
• The delivery status

If the delivery status is SENT, then you should also provide the time at which the delivery was executed. If the delivery status is NOT_SENT, then you have the option to provide a reason why it wasn't sent. If you don't call this mutation to provide Shopify with the delivery status, then the status will always display as Not sent in the Recovery automation results section.

Anchor to Step 4: Test the action and data updatesStep 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.

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

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

3. In the Marketing page, in the Recent marketing activities section, make sure that your marketing activity appears in the list with a unique name.

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

5. If the workflow uses the Customer abandons checkout trigger, then in the Abandoned checkout details page, in the Recovery automation results section, make sure that your marketing activity has the correct delivery status upon workflow run completion.