---
title: Flow action reference
description: >-
  A reference guide on how to customize your Flow action TOML configuration
  file.
source_url:
  html: 'https://shopify.dev/docs/apps/build/flow/actions/reference'
  md: 'https://shopify.dev/docs/apps/build/flow/actions/reference.md'
---

# Flow action reference

The guide provides a comprehensive reference on how to customize your Flow action TOML configuration file. It covers all sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.

The guide also provides optional sections on adding a custom configuration page, configuring custom validation, and adding a custom return data type.

***

## TOML

**Note:**

Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. To create Flow extensions using [Shopify CLI](https://www.npmjs.com/package/@shopify/cli), ensure you have the latest version installed.

When you create a new action extension through Shopify CLI, you get a basic version of the `shopify.extension.toml` file structure that looks like the following example:

## toml

```terminal
[[extensions]]
name = "Place auction bid"
type = "flow_action"
handle = "place-auction-bid"
description = "Your description"
runtime_url = "/api/flow/actions/place-bid"


[settings]


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


  [[settings.fields]]
  type = "single_line_text_field"
  key = "your-field-key"
  name = "Display name"
  description = "A description of my field"
  required = true
```

### Action extension properties

These are flow-specific properties for your Flow extension. They're included in the `[[extensions]]` section of the TOML file.

You can choose either URL format for `runtime_url`, `validation_url`, `config_page_url`, and `config_page_preview_url`:

* Absolute HTTPS URLs, such as `https://example.com/api/flow/actions/place-bid`. Use an absolute URL when the endpoint is hosted outside of your app or you want Flow to call a specific URL in every environment.
* Relative paths that start with a single `/`, such as `/api/flow/actions/place-bid`. If you're using your app URL as the endpoint, then Shopify recommends a relative path because your development tunnel URL can change each time you run [`app dev`](https://shopify.dev/docs/api/shopify-cli/app/app-dev). Shopify CLI resolves relative paths against your development tunnel URL during `app dev`, and against the `application_url` in your app configuration during deploy.

Protocol-relative URLs, such as `//example.com/api/execute`, aren't supported. If you use a relative path, then your app configuration must include an HTTPS `application_url` before you deploy.

This relative path support applies to top-level Flow action URL fields only. It doesn't apply to the marketing activity URLs that are configured on the `marketing_activity_reference` field.

| Property name | Description | Rules |
| - | - | - |
| `name` required | The name of your extension. This is your task's merchant-facing name in the editor. This name should be human-readable. | |
| `type` required | The type of your extension. This should always be set to `flow_action` for Flow actions. | - Value must be `"flow_action"`. |
| `handle` required | A unique identifier for your extension. | - Must be unique across your app's extensions. - Must only contain alphanumeric characters and hyphens. |
| `description` required | A description of your extension. This description displays in the Flow editor navigation panel. | |
| `runtime_url` required | The endpoint where Flow sends your action's payload when your step is being executed at runtime. [The payload](https://shopify.dev/docs/apps/build/flow/actions/endpoints#flow-action-execution) contains data that you can use to execute the action in your app. | - Must be an absolute HTTPS URL or a relative path that starts with a single `/`. |
| `validation_url` optional | [An endpoint](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-validation) that validates the contents of custom fields in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page. | - Must be an absolute HTTPS URL or a relative path that starts with a single `/`. |
| `config_page_url` optional | A route that renders your [custom configuration page](https://shopify.dev/docs/apps/build/flow/actions/build-config-ui). | - Must be an absolute HTTPS URL or a relative path that starts with a single `/`. |
| `config_page_preview_url` optional | [An endpoint](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-configuration-page-preview) 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. | - Must be an absolute HTTPS URL or a relative path that starts with a single `/`. |
| `schema` optional | A relative file path to a [GraphQL schema definition file](https://shopify.dev/docs/apps/build/flow/configure-complex-data-types#sdl-file) that contains custom types that you can use as part of your action. | - Must be a relative path to a GraphQL file. |
| `return_type_ref` optional | The name of [the type to be returned](https://shopify.dev/docs/apps/build/flow/configure-complex-data-types#referencing-the-return-type-schema-in-an-action-extensions-toml) by the action. | - Must be a type that's present in the schema file. |

### Action extension fields

Extension fields are listed in the `[settings]` section, with each field using a `[[settings.fields]]` header. These fields render in your action's configuration panel in the Flow editor. You can include two types of fields in your payload schema: [reference fields](#reference-field-types) and [custom fields](#custom-field-types). Fields are present to merchants in the same order that they are defined in the TOML file.

| Property name | Description | Rules |
| - | - | - |
| `type` required | The field type. | - [Accepted custom field types](#custom-field-types). - [Accepted reference field types](#reference-field-types). |
| `key` optional | A unique key that identifies your field. This key will be sent at runtime along with the value of the field. | - Required for custom field types. |
| `name` optional | The field’s merchant-facing name. | - Required for custom field types. |
| `description` optional | A description of the field. This will appear in the Flow editor configuration panel. | |
| `required` optional | A boolean value to make the field required in the Flow editor. | - Must be a boolean value. |
| `marketingActivityCreateUrl` optional | A URL for marketing activity creation when the field has the `marketing_activity_reference` type. 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. | - Use an absolute HTTPS URL. Shopify CLI doesn't resolve relative paths for this field. |
| `marketingActivityDeleteUrl` optional | A URL for marketing activity deletion when the field has the `marketing_activity_reference` type. This endpoint is called when a workflow associated with the marketing activity is deleted. | - Use an absolute HTTPS URL. Shopify CLI doesn't resolve relative paths for this field. |

***

## Supported field types

When you create an action, you add the fields that your action endpoint requires merchants to provide. You set up these fields in the `[settings]` section of the TOML file.

### Reference field types

Reference fields are Shopify resources that can be used by your action. The ID for the resource is usually populated automatically by a workflow trigger, making it easier for your merchants to use. 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.

| Reference type (TOML) | Payload key | Description |
| - | - | - |
| `customer_reference` | `customer_id` | The [`id`](https://shopify.dev/docs/api/admin-rest/current/resources/customer#resource-object) of the customer. Your app must have the `read_customers` scope. |
| `order_reference` | `order_id` | The [`id`](https://shopify.dev/docs/api/admin-rest/current/resources/order#resource-object) of the order. Your app must have the `read_orders` scope. |
| `product_reference` | `product_id` | The [`id`](https://shopify.dev/docs/api/admin-rest/current/resources/product#resource-object) of the product. Your app must have the `read_products` scope. |
| `company_reference` | `company_id` | The [`id`](https://shopify.dev/docs/api/admin-graphql/current/objects/company#field-company-id) of the company. Your app must have the `read_companies` scope. |
| `company_contact_reference` | `company_contact_id` | The [`id`](https://shopify.dev/docs/api/admin-graphql/current/objects/companycontact#field-companycontact-id) of the company contact. Your app must have the `read_companies` scope. |
| `abandonment_reference` | `abandonment_id` | The [`id`](https://shopify.dev/docs/api/admin-graphql/current/objects/Abandonment) of the abandonment. |
| `marketing_activity_reference` | `marketing_activity_id` | The [`id`](https://shopify.dev/docs/api/admin-graphql/current/objects/MarketingActivity) of the marketing activity. |

### Custom field types

Custom field types are fields for merchants to populate as a part of the action configuration. When the action is executed, the merchant-configured values are passed as a part of the action payload.

The following are the available custom field `types`:

| Field type | Description |
| - | - |
| `boolean` | A Boolean value. This field is represented as a checkbox in the Flow Editor configuration panel. |
| `email` | A text field that has native email validation. |
| `single_line_text_field` | A single line text field. |
| `multi_line_text_field` | A multi-line text field. |
| `number_decimal` | A number field with a decimal point. |
| `number_integer` | An integer number field. |
| `url` | A text field that has native URL validation. |

***

## Handling Flow action requests

Your application logic must be able to handle incoming Flow action requests with a route in your app. The URL of this route should match the `runtime_url` configured in your extension's `shopify.extension.toml` file.

For more information on how to handle Flow action requests, refer to [Flow action execution](https://shopify.dev/docs/apps/build/flow/actions/endpoints#flow-action-execution).

***

## Advanced topics

### Optional: 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 Flow, you can embed a page from your app in the Shopify Flow 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 Flow. [Learn how to build a custom configuration page](https://shopify.dev/docs/apps/build/flow/actions/build-config-ui).

A custom configuration page also requires a [custom configuration page preview endpoint](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-configuration-page-preview) 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. The custom configuration page URL and preview URL can be either absolute HTTPS URLs or relative paths that start with a single `/`.

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.

### Optional: 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](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-validation) where Shopify Flow 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. The custom validation URL can be either an absolute HTTPS URL or a relative path that starts with a single `/`.

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.

### Optional: Add a custom return data type

To return data from an action, you must provide a schema for the return type using GraphQL's type system (SDL) so that Flow can properly provide the return object in the workflow editor. You can define this schema in any file and link to it from the TOML. For example, a file called `schema.graphql` can be made in the same directory as the extension that's referring to the SDL.

For more information, please consult our [complex data types](https://shopify.dev/docs/apps/build/flow/configure-complex-data-types) section.

***