Flow template reference

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.

Anchor to TOMLTOML

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:

shopify.extension.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

Anchor to Flow template extension fieldsFlow template extension fields

Property	Description	Rules
`name` required	The title of the template. This property is translatable and will use the value for the key `name` in the translation files.
`type` required	The type of your extension. This should always be set to `flow_template` for Flow templates.	- Value must be `flow_template`.
`handle` required	A globally-unique identifier for your extension. This property can't be changed after you’ve run the `app dev` or `deploy` command.	- Can't exceed 30 characters. - Must only contain alphanumeric characters and hyphens.
`description` optional	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` required	The categories that best describe the function of your template.	- Must be an array containing only strings of valid categories. - Must choose at least one category. Max 2 recommended. - Valid categories are: `buyer_experience`, `customers`, `inventory_and_merch`, `loyalty`, `orders`, `promotions`, `risk`, `fulfillment`, `b2b`, `payment_reminders`, `custom_data`, and `error_monitoring`.
`module` required	The file path of the template workflow in the extension's folder.
`require_app` optional	Whether your template is visible only to merchants who have your app installed.	- Defaults to `false`. - Must be set to `true` if the app's type is `Custom`.
`discoverable` optional	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` optional	Whether you template should be published and made available after being approved.	- Defaults to `true`.

Anchor to LocalizationLocalization

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 added within the workflow.

Anchor to Adding additional localesAdding 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.

Anchor to Step descriptionsStep 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

en.default.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"

}

Anchor to Approval processApproval process

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

Anchor to WorkflowWorkflow

Provides value/solves a problem. For example, notifying the merchant when a buyer makes 10 purchases and adds a VIP tag to the customer.

Does not already exist within the template library.

Isn't malicious in its execution.

Is complete in its configuration. Validation errors might exist in the workflow where fields are left blank for input unique to the merchant.

Anchor to TOMLTOML

Titles should use the format, "<Description of key action> when <description of trigger>".

Includes all required fields.

Anchor to LocalizationLocalization

Has correct spelling and grammar.

Has a default localization, for example en.default.json.

Has an English translation.

Include the preInstallNote field if setup is required before the template can be turned on. If no prior setup is needed, then remove the preInstallNote field from the localization files before submitting the template extension.

Anchor to AccessAccess

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.

Anchor to LimitationsLimitations

A maximum of 25 templates can be submitted for each app.

App type must be Public or Custom.

Public apps must be listed in the Shopify App Store prior to submitting a template.

Custom apps must have require_app set to true.

Don't edit the .flow file directly. Only change and export updated workflows using the Flow app.

Anchor to Submitting your extension for approvalSubmitting your extension for approval

After you're satisfied with your template extension, 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.

Was this page helpful?