Skip to main content

Create a Flow action

To create an action that merchants can use in their workflows, you need to add the action to your app. The action needs to contain the following information:

  • The fields that the merchant needs to complete when they add the action to their workflows

  • The URL that Shopify Flow uses to send (POST) the contents (JSON payload) of the action to your app

    You also need to configure your app to process the data from the POST request when it arrives and to send status codes back to Shopify Flow.

    To enhance the merchant experience and more closely integrate external systems, you can also build a custom configuration page. To improve the reliability of your action, you can add custom validation for action properties.

Anchor to RequirementsRequirements

  • You have the following:
    • A test web server that has access to the Internet, so that it can receive POST requests from Shopify Flow
    • A test app that works with the test web server
    • A dev store that has Shopify Flow and the test app installed

Anchor to Step 1: Create a Flow ActionStep 1: Create a Flow Action

To give your Flow action a meaningful name, use the following guidelines:

  • Use a present-tense verb + object acted on format. For example, Place auction bid.
  • Use sentence case.
  • Don't use punctuation.
  • Separate words using spaces.

Anchor to Using Shopify CLIUsing Shopify CLI

Use the Shopify CLI to generate a new extension:

  1. Navigate to your app directory.
  2. Run the following command:

Terminal

#!/bin/bash
shopify app generate extension
  1. Select the Flow Action as the type of extension.
  2. Provide a meaningful name for your extension.

After you've followed the prompts, Shopify CLI generates the extension’s file representation in your app's /extensions directory and gives you a success message. You can then go into your app's /extensions directory and start editing your new extension.

The file structure of your extension should look like the following:

/place-auction-bid
shopify.extension.toml

To learn more about the extensions file structure, refer to App structure and the documentation for your extension type.

Anchor to Step 2: Customize a Flow action configuration fileStep 2: Customize a Flow action configuration file

In this section you'll use the default action template and update it to be a functional extension example. Once you have generated a Flow extension using Shopify CLI, follow the instructions below:

  1. Change the description to Place a bid on an auction.
  2. Update the extensions.runtime_url to an endpoint where you can receive the runtime request.
  3. On the second settings.fields field, update the following values:
  • type to number_decimal
  • key to amount
  • name to Bid Amount
  • Add a description property and set it to The amount of the bid

toml

[[extensions]]
name = "Place Auction Bid"
type = "flow_action"
handle = "place-bid"
description = "Place a bid on an auction"
runtime_url = "https://your-server-domain/path/to/action/handler"

[settings]

[[settings.fields]]
type = "customer_reference"
required = true

[[settings.fields]]
type = "number_decimal"
key = "amount"
name = "Bid Amount"
description = "The amount of the bid"
required = true

Anchor to Step 3: Configure your web serverStep 3: Configure your web server

To build a Shopify Flow action, you need to add a service to your web server to listen for the JSON payload that Shopify Flow sends when the action runs.

Optionally, you can also add the following:

  • An endpoint to validate actions

  • A custom configuration page, and an endpoint that lets merchants preview your custom configuration page

    Add the following API endpoints to your server:

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

Custom configuration page preview

An endpoint that provides data about your custom configuration page to display in the automation tool. This endpoint is required if you want to use a custom configuration page.

Custom validation

An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page.

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 Step 4: Enable the draft version of your actionStep 4: Enable the draft version of your action

Running app dev allows changes made to local files to update the draft version of your Flow task extensions. The draft version is only available in your development store.

Note

When app dev is running, the preview version of a task will appear in your chosen development store in place of the deployed version. Other shops will continue to see the deployed version of your task (if one exists). Preview versions can be identified by the "draft" badge. To see the deployed version of the task in your development store, stop the development preview by running shopify app dev clean.

  1. Navigate to your app directory.
  2. Run the following command to start using draft versions of your extension(s):
#!/bin/bash
shopify app dev
  1. Follow the prompts.

Anchor to Step 5: Test the actionStep 5: Test the action

After you've created an action and added support for it in your web server, you can test the action in Shopify Flow on your dev store.

  1. In your dev store, create a workflow that uses the action. For example, add the trigger that you created in the Triggers guide and this action to a workflow.

  2. If you created a custom configuration page, then ensure that the preview displays and that the custom configuration page is accessible.

  3. If you added any custom validation, then ensure that it works as expected.

  4. Trigger the workflow. For example, in your web server, run the event that sends the trigger information to Shopify Flow.

When the workflow completes, your web server has sent data to Shopify Flow because of the trigger. Shopify Flow has sent this data to a web server that logged the information to its console because of the action.

Anchor to Step 6: Deploy your extensionStep 6: Deploy your extension

Note

Deploying extensions using the app deploy command also publishes the extensions. We recommend testing changes by using app dev or deploying to a test app before deploying them to a production app.

Use Shopify CLI to deploy your extensions:

  1. Navigate to your app directory.

  2. Run the following command to deploy your extension(s):

    Terminal

    shopify app deploy

  3. Follow the prompts.

When you receive confirmation that the deploy was successful, your extensions have been released.

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 handle. This ID should match the handle of the action that you created, and can be retrieved from the payload preview.

Anchor to Next stepsNext steps

Was this page helpful?