data/scraped/clean/flow_templates_reference.txt

This guide provides explanations of key topics for building and deploying a Flow template extension. This includes the TOML configuration file, localization, and the template approval process.

## TOML

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

```toml
[[extensions]]
name = "t:name"
type = "flow_template"
handle = "example-name"
description = "t:description"

[extensions.template]

categories = ["orders", "risk"]

module = "./template.flow"

require_app = false

discoverable = true

enabled = true
```

### Flow template extension fields

| Property | Description                                                                     | Rules             |
| ------------- | ---------------------------------------------------------------------------------- | ----------------- |
| `name` <br><span class="heading-flag">Required</span> | The title  of the template. This property is translatable and will use the value for the key `name` in the translation files.  | |
| `type` <br><span class="heading-flag">Required</span> | The type of your extension. This should always be set to `flow_template` for Flow templates.| - Value must be `flow_template`. |
| `handle` <br><span class="heading-flag">Required</span> | A globally-unique identifier for your extension. This property can't be changed after you’ve run the [`app dev`](/docs/api/shopify-cli/app/app-dev) or [`deploy`](/docs/api/shopify-cli/app/app-deploy) command. | - Can't exceed 30 characters.<br /> - Must only contain alphanumeric characters and hyphens. |
| `description` <br><span class="heading-flag">Optional</span> | The description of your template's workflow. This property is translatable and will use the value for the key `description` in the translation files. | |
| `categories` <br><span class="heading-flag">Required</span> | The categories that best describe the function of your template. | - Must be an array containing only strings of valid categories. <br /> - Must choose at least one category. Max 2 recommended. <br /> - Valid categories are: `buyer_experience`, `customers`, `inventory_and_merch`, `loyalty`, `orders`, `promotions`, `risk`, `fulfillment`, `b2b`, `payment_reminders`, `custom_data`, and `error_monitoring`. |
| `module`  <br><span class="heading-flag">Required</span> | The file path of the template workflow in the extension's folder. |
| `require_app` <br><span class="heading-flag">Optional</span> | Whether your template is visible only to merchants who have your app installed. | - Defaults to `false`. |
| `discoverable` <br><span class="heading-flag">Optional</span> | Whether your template should be displayed in the template browser. When `false`, the template is accessible only through a deep link. | - Defaults to `true`. |
| `enabled` <br><span class="heading-flag">Optional</span> | Whether you template should be published and made available after being approved. | - Defaults to `true`.

## Localization

Localizing your template by providing translated text allows a wider audience to understand your template better and can increase adoption.

You can provide translations for the following fields:

- **`name`**: Title of the template.
- **`description`**: Description of the template and it's purpose.
- **`preInstallNote`**: (Optional): Instructions for merchants to complete before activating the workflow. This field should only be included if setup is required before the template can be turned on.
- [Custom step descriptions](#step-descriptions) added within the workflow.

### Adding additional locales

Add new `.json` files prefixed with the locale, for example `es.json`.

Add `default` to one of the locales to make it the fallback if a merchant's locale isn't in the locales you have provided. Example: `en.default.json`.

### Step descriptions

You can provide translated custom step descriptions by adding a translation key wrapped by curly braces in the step description field. For example, `{expressShippingCondition}`. Ensure there's no other characters before or after `{yourKey}`. After adding this to your workflow, you can update the translation files to include the step description.

The following is an example:

![How to format localized step descriptions in the Flow editor](/assets/apps/flow/localized_step_descriptions_in_flow_editor.png)

```json
{
  "name": "My Awesome Template!",
  "description": "A template that helps increase merchant productivity",
  "preInstallNote": "You must disable automatic payment capture in the Shopify Admin before using this template",
  "expressShippingCondition": "This step will check if the order uses express shipping"
}
```

## Approval process

Before submitting your template extension for approval ensure that it meets the following criteria:

### Workflow

<input class="marketing-checkbox" type="checkbox" id="template-criteria-1">
<label class="marketing-checkbox-label" for="template-criteria-1">
  <p style="margin-left:30px">Provides value/solves a problem. For example, notifying the merchant when a buyer makes 10 purchases and adds a `VIP` tag to the customer.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-2">
<label class="marketing-checkbox-label" for="template-criteria-2">
  <p style="margin-left:30px">Does not already exist within the [template library](https://admin.shopify.com/apps/flow/web/editor/templates).</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-3">
<label class="marketing-checkbox-label" for="template-criteria-3">
  <p style="margin-left:30px">Isn't malicious in its execution.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-4">
<label class="marketing-checkbox-label" for="template-criteria-4">
  <p style="margin-left:30px">Is complete in its configuration. Validation errors might exist in the workflow where fields are left blank for input unique to the merchant.</label>

### TOML

<input class="marketing-checkbox" type="checkbox" id="template-criteria-5">
<label class="marketing-checkbox-label" for="template-criteria-5">
  <p style="margin-left:30px">Titles should use the format, "\<Description of key action\> when \<description of trigger\>".</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-6">
<label class="marketing-checkbox-label" for="template-criteria-6">
  <p style="margin-left:30px">Includes all required fields.</label>

### Localization

<input class="marketing-checkbox" type="checkbox" id="template-criteria-7">
<label class="marketing-checkbox-label" for="template-criteria-7">
  <p style="margin-left:30px">Has correct spelling and grammar.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-8">
<label class="marketing-checkbox-label" for="template-criteria-8">
  <p style="margin-left:30px">Has a default localization, for example <code>en.default.json</code>.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-9">
<label class="marketing-checkbox-label" for="template-criteria-9">
  <p style="margin-left:30px">Has an English translation.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-10">
<label class="marketing-checkbox-label" for="template-criteria-10">
  <p style="margin-left:30px">Include the <code>preInstallNote</code> field if setup is required before the template can be turned on. If no prior setup is needed, then remove the <code>preInstallNote</code> field from the localization files before submitting the template extension.</label>

### Access

<input class="marketing-checkbox" type="checkbox" id="template-criteria-11">
<label class="marketing-checkbox-label" for="template-criteria-11">
  <p style="margin-left:30px">Flow’s testing account, at flow-connector-testing.myshopify.com has access to any actions, triggers, or resources that are required to test the templates, including access to the app.</label>

### Limitations

<input class="marketing-checkbox" type="checkbox" id="template-criteria-12">
<label class="marketing-checkbox-label" for="template-criteria-12">
  <p style="margin-left:30px">A maximum of 25 templates can be submitted for each app.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-13">
<label class="marketing-checkbox-label" for="template-criteria-13">
  <p style="margin-left:30px">Public apps must be listed in the [Shopify App Store](https://apps.shopify.com/) prior to submitting a template.</label>

<input class="marketing-checkbox" type="checkbox" id="template-criteria-14">
<label class="marketing-checkbox-label" for="template-criteria-14">
  <p style="margin-left:30px">Don't edit the `.flow` file directly. Only change and export updated workflows using the Flow app.</label>

### Submitting your extension for approval

After you're satisfied with your template extension, [`deploy`](/docs/api/shopify-cli/app/app-deploy) a new app version from Shopify CLI. The Flow team will review your templates within three business days. Template reviews don't block your app version from releasing, but template changes won't be reflected until the approval process is complete. If we require changes, then we'll reject the review and follow up through email with feedback.