[ Web Proxy ]
URL:
Viewing: https://shopify.dev/docs/apps/build/flow/templates/reference [Back]  [Original]
Flow template referenceSkip to main content
Docs page [Docs page]Docs page [Docs page]
Apps
Collapse sidebar
Full index
ExpandOn this page

Flow template reference

Install AI ToolkitAsk about this pageCopy MD

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 extension through the Shopify CLI, you get a basic version of the shopify.extension.toml file structure that looks like the following example:

shopify.extension.toml

Copy
[[extensions]]
name = "t:name"
type = "flow_template"
uid = "0edf5af1-33e7-bff6-7c0d-04106abcf7bf7c094e99"
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

PropertyDescriptionRules
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 youve run the app dev or deploy command.- Must only contain alphanumeric characters and hyphens.
description
required		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, promotion, 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 your template should be published and made available after being approved.- Defaults to true.
allow_one_click_activate
optional		Whether merchants can activate your template with a single click, without any additional configuration. Set this to true only when your workflow has no fields that require merchant-specific input.- Defaults to false.

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 its 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 [How to format localized step descriptions in the Flow editor]

en.default.json

Copy
{
"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?
YesNo
Web Proxy Viewer  |  New URL  |  Original Page