Action endpoints
Before your app can receive communication from marketing automation actions, you need to create one or more standardized API endpoints on your web server. Review the information for each endpoint to understand the requirements for each endpoint, the format of the payload sent to the endpoint, and the expected response. You'll also learn how to avoid processing duplicate requests, identify an action by its ID, and verify requests for security purposes.
| Endpoint | Purpose |
|---|---|
| Flow action execution | 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. |
| Marketing activity create | 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. |
| Marketing activity delete | The endpoint that's called when a workflow associated with the marketing activity is deleted. This endpoint is called when a workflow associated with the marketing activity is deleted. |
General endpoint requirements
Anchor link to section titled "General endpoint requirements"The requirements for Shopify Flow action endpoints are as follows:
| Rule / concern | Type / requirement |
|---|---|
| API format | REST |
| Content type | JSON |
| Security mechanism | HMAC / Signed requests |
| Protocol | HTTPS (app domain requires valid SSL certificate) |
Flow action execution
Anchor link to section titled "Flow action execution"The Flow action execution endpoint is where the automation tool sends your action's payload.
The request contains a payload that matches the payload schema you configured for your action.
The payload contains the following parameters:
| Parameter | Description |
|---|---|
shop_id |
The ID of the store. |
shopify_domain |
The myshopify.com domain of the store. |
action_run_id |
An ID that represents an instance of an action being run. Learn more. |
action_definition_id |
A unique ID for the action. The ID is based on the action name in the Partner Dashboard. |
properties |
The properties that you selected for your payload schema in the action configuration. |
To learn how to configure the payload schema, refer to Shopify marketing automation actions.
Expected response
Anchor link to section titled "Expected response"After the automation tool sends a POST request to your web server, it waits for a maximum of 10 seconds for an HTTP status code.
If after 10 seconds the automation tool hasn't received a response from your web server, then the automation tool closes the connection to your web server and resends the request later.
When the automation tool receives a response, it processes the codes as displayed in the following table:
| Status codes | Description |
|---|---|
| 200 Success | The automation tool assumes that the POST request has been processed by your web server. |
| 202 Success | The automation tool assumes that the POST request has been accepted but not processed by your web server. The automation tool will resend the POST request at increasing intervals for up to 24 hours. |
| 4XX Client errors |
If your web server sends a 429 status code without a If your web server sends a 429 status code with a
If your web server sends any other 4XX code, then the automation tool assumes that there was a failure and it doesn't resend the POST request. Merchants see a notification in the automation tool that includes the raw contents of your web server's response. Example: You can provide a merchant-friendly description of the error by adding a key named Example: |
| 5XX Server errors | The automation tool resends the POST request at increasing intervals for up to 24 hours. |
| Other status code | If your web server returns a code that isn't described in this table, then the automation tool assumes that there was a failure and it doesn't resend the POST request. |
Prevent apps from processing duplicate requests
Anchor link to section titled "Prevent apps from processing duplicate requests"Each request from an automation workflow contains an action_run_id that's unique to the associated action run. This ID is included in the body of the request.
You can use action_run_id as an idempotency key to check if the request is unique. In some cases, your app could receive an identical request more than once. For example, the automation tool might resend a request because it didn't receive your response in time. Your app can store the idempotency key in a cache with a set expiry time to avoid reprocessing duplicate requests.
Identify actions
Anchor link to section titled "Identify actions"When you create an action, an action_definition_id is assigned to it.
You can find an action's action_definition_id in its Payload preview in the Partner Dashboard:
The action_definition_id is sent as part of the payload when the action is run. When your web server receives a request, verify that the action_definition_id matches the ID of an action that you created.
If you've created multiple actions, then you can also use the action_definition_id to sort the payload contents for processing in your web server or app.
Marketing activity create
Anchor link to section titled "Marketing activity create"The marketing activity create endpoint is called when a step in a workflow is created using a marketing automation action.
The payload contains the following parameters:
| Parameter | Description |
|---|---|
shop_id |
The ID of the store. |
shopify_domain |
The myshopify.com domain of the store. |
step_reference |
A unique ID for the step within a workflow. |
marketing_activity_id |
The ID for the marketing activity. You need to reference this ID when you send marketing data and insights back to Shopify. |
automation_step_type |
An enum that represents the intent of the action, based on the marketing automation trigger. You should use this attribute to render default content. |
locale |
The locale of the customer whose action in the store triggered the workflow action. |
Automation step types
Anchor link to section titled "Automation step types"The following are valid values for the automation_step_type attribute. Use these values to render default content based on the action's intent.
| Value | Intent |
|---|---|
abandoned_browse |
Encourage customers who browsed a product page without adding products to the cart to make a purchase. |
abandoned_checkout |
Encourage customers who didn't finish the checkout process to complete their purchase. |
abandoned_cart |
Encourage customers who left items in their cart to complete their purchase. |
free_form |
No predefined intent. The action was triggered by a custom automation. |
upsell |
Encourage first-time customers to return to the store. |
welcome_email |
Welcome new email subscribers to the store. This intent excludes customers who subscribed at checkout. |
winback |
Drive customers who haven't made a purchase in a long time back to the store. |
Expected response
Anchor link to section titled "Expected response"When a request is received, the marketing activity create endpoint should respond with an HTTP 200. Any response other than an HTTP 200 is interpreted as an error.
The response must contain the following parameters:
| Parameter | Description |
|---|---|
tactic |
Accepted values: message, notification, or newsletter |
channel |
Accepted values: email, sms |
UTM parameters (utm_campaign, utm_source, utm_medium) |
The UTM parameter combination must be unique to each marketing activity in the store. |
Marketing activity delete
Anchor link to section titled "Marketing activity delete"Marketing activity delete is called when a workflow associated with the marketing activity is deleted.
The payload contains the following parameters:
| Parameter | Description |
|---|---|
shop_id |
The ID of the store. |
shopify_domain |
The myshopify.com domain of the store. |
step_reference |
A unique ID for the step within a workflow. |
marketing_activity_id |
The ID for the marketing activity. |
Expected response
Anchor link to section titled "Expected response"When a request is received, the marketing activity delete endpoint should respond with an HTTP 200. Any response other than an HTTP 200 is interpreted as an error. The request will be retried up to 5 times using exponential back-off.
Verifying requests
Anchor link to section titled "Verifying requests"For security reasons, your web service should enforce a hash-based message authentication (HMAC) header verification that uses the client secret that you created when you configured your app.
The name of the HMAC header is x-shopify-hmac-sha256. If you are using a Ruby-based web framework, then the name of the header is http-x-shopify-hmac-sha256.
When the action runs in a workflow, the automation tool posts the contents (JSON payload and the HMAC header) of the action to the URL that you entered when you created the action in the Partner Dashboard. When your web server receives the POST request, it needs to verify the HMAC header against the JSON payload and your app's API secret. The HMAC verification works the same as webhooks.
Your web server also needs to verify that the action_definition_id that's sent in the payload matches the ID of an action that you created.
After you've verified the HMAC header, you can process the contents of the payload. For example, you could log the contents of the payload to your web server's console.