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.
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:
Flow template extension fields
Anchor link to section titled "Flow 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. |
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. |
Localization
Anchor link to section titled "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: Instructions for merchants to complete before activating the workflow.- Custom step descriptions added within the workflow.
Adding additional locales
Anchor link to section titled "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
Anchor link to section titled "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:
Approval process
Anchor link to section titled "Approval process"Before submitting your template extension for approval ensure that it meets the following criteria:
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.
Titles should use the format, "<Description of key action> when <description of trigger>".
Includes all required fields.
Localization
Anchor link to section titled "Localization"
Has correct spelling and grammer.
Has a default localization, for example en.default.json.
Has an English translation.
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.
Submitting your extension for approval
Anchor link to section titled "Submitting your extension for approval"After you're satisfied with your template extension, deploy a new app version from Shopify CLI, and request a review of the new version from your Partner Dashboard. The Flow team will review your templates within one to two business days. If we require changes, then we'll reject the review and follow up through email with feedback.