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:

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="bash" data-title="toml">
[[extensions]]
name = "Place auction bid"
type = "flow_action"
handle = "place-auction-bid"
description = "Your description"
runtime_url = "https://{url}.com/api/execute"

[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
</script>

</div>
</p>


### Action extension fields

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

| Property name | Description                                                                     | Rules             |
| ------------- | ---------------------------------------------------------------------------------- | ----------------- |
| `name` <br><span class="heading-flag">Required</span> | The name of your extension. This is your task's merchant-facing name in the editor. This name should be human-readable. | |
| `type` <br><span class="heading-flag">Required</span> | The type of your extension. This should always be set to “flow_action” for Flow actions.| - Value must be `"flow_action"`. |
| `handle` <br><span class="heading-flag">Required</span> | A unique identifier for your extension. This property can't be changed after you’ve run the `dev` or `deploy` command. | - Can't exceed 30 characters.<br /> - Must be unique across your app's extensions. <br /> - Must only contain alphanumeric characters and hyphens. |
| `description` <br><span class="heading-flag">Optional</span> | A description of your extension. This description displays in the Flow editor navigation panel. | |
| `runtime_url` <br><span class="heading-flag">Required</span> | The endpoint where Flow sends your action's payload when your step is being executed at runtime. [The payload](/docs/apps/build/flow/actions/endpoints#flow-action-execution) contains data that you can use to execute the action in your app. | - Must be a URL. |
| `validation_url`  <br><span class="heading-flag">Optional</span> | [An endpoint](/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 a URL. |
| `config_page_url` <br><span class="heading-flag">Optional</span> | A route that renders your [custom configuration page](/docs/apps/build/flow/actions/build-config-ui). | - Must be a URL. |
| `config_page_preview_url` <br><span class="heading-flag">Optional</span> | [An endpoint](/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 a URL. |
| `schema` <br><span class="heading-flag">Optional</span> | A relative file path to a [GraphQL schema definition file](/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` <br><span class="heading-flag">Optional</span> | The name of [the type to be returned](/docs/apps/build/flow/configure-complex-data-types#referencing-the-return-type-schema-in-an-action-extensions-toml) by the action. This type must be present in the referenced schema file. | - 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.field]]` 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` <br><span class="heading-flag">Required</span> | The field type. | - [Accepted custom field types](#custom-field-types).<br /> - [Accepted reference field types](#reference-field-types). |
| `key` <br><span class="heading-flag">Optional</span> | 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` <br><span class="heading-flag">Optional</span> | The field’s merchant-facing name. | - Required for custom field types. |
| `description` <br><span class="heading-flag">Optional</span> | A description of the field. This will appear in the Flow editor configuration panel. |  |
| `required` <br><span class="heading-flag">Optional</span> | A boolean value to make the field required in the Flow editor. | - Must be a boolean value. |
| `marketingActivityCreateUrl` <br><span class="heading-flag">Optional</span> | 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. |  |
| `marketingActivityDeleteUrl` <br><span class="heading-flag">Optional</span> | 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. |  |

## 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`](/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`](/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`](/docs/api/admin-rest/current/resources/product#resource-object) of the product. Your app must have the `read_products` scope. |
| `abandonment_reference` | `abandonment_id` | The [`id`](/docs/api/admin-graphql/current/objects/Abandonment) of the abandonment. | 
| `marketing_activity_reference` | `marketing_activity_id` | The [`id`](/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.                                                                 |

## 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](/docs/apps/build/flow/actions/build-config-ui).

A custom configuration page also requires a [custom configuration page preview endpoint](/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.

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](/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.

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](/docs/apps/build/flow/configure-complex-data-types) section.