Marketing activities components reference
The creation of new marketing activity app extensions is deprecated. Only existing extensions can still be managed. If you have an existing marketing activity app extension and would like to continue to manage it, please migrate it to CLI following the migration guide.
The form that's associated with a marketing activity app extension is generated based on a set of components that you choose when you create it. Components are configurable pieces of UI that you can use to build out the specific functionality that your app requires. Although a form is generated based on the components that you choose, you can't customize its styling, layout, or workflows directly.
Anchor to How it worksHow it works
When an app user interacts with your marketing activity, Shopify calls your marketing activity preload endpoint to render the field values that your app provides. To do this Shopify uses the components in JSON format, as defined in this document. The JSON format is also used for your app's other endpoints such as create and update.
Anchor to Preload endpoint JSON output schemaPreload endpoint JSON output schema
Responses from your app's preload endpoint include the form_data
at the top level with field_name
and property key value pairs.
For the dynamic standalone endpoint, responses from your app include component_data
at the top level. Refer to the typeahead component for more information.
Anchor to Create or update JSON input schemaCreate or update JSON input schema
When a user creates or updates a marketing activity, Shopify calls your app by sending the properties object with the included field names and corresponding values.
Anchor to Extensions configured with Shopify CLIExtensions configured with Shopify CLI
Shopify CLI builds and serves app extensions using information defined in a TOML file. Components are specified in the fields
section of your marketing activity extension's TOML file. The following is an example TOML file:
shopify.extension.toml
For every component in fields
, regardless of the type, the following subfields are mandatory:
Subfield | Description |
---|---|
name required | The API identifier. Use snake_case : lowercase letters, numbers, and underscores only. |
ui_type required | The type of the field component. |
Each type of component requires different additional subfields. For a complete reference, and to determine the ui_type
of the component you wish to configure, read on.
Anchor to Single line of textSingle line of text
Use this component to let users provide text input when the expected input is short.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the component. |
hidden | Boolean | Whether the component is hidden. Default: false . |
max_length | Number | The maximum number of characters allowed. |
min_length | Number | The minimum number of characters allowed. |
placeholder | String | The hint text to display. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | String | The value of the input. |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the help text and value of the ad_title
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the ad_title
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | Must be one of text-single-line , text-email , text-tel , text-url |
label required | String |
required required | Boolean |
help_text | String |
placeholder | String |
min_length required | Number |
max_length required | Number |
Anchor to Multiple lines of textMultiple lines of text
Use this component when the expected input could be more than one line. The component will automatically grow to accommodate additional text.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the component. |
hidden | Boolean | Whether the component is hidden. Default: false . |
max_length | Number | The maximum number of characters allowed. |
min_length | Number | The minimum number of characters allowed. |
placeholder | String | The hint text to display. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | String | The value of the input. |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the help text and value of the ad_body
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the ad_body
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | text-multi-line |
label required | String |
required required | Boolean |
help_text | String |
placeholder required | String |
min_length required | Number |
max_length required | Number |
Anchor to NumberNumber
Use this component to let users provide number input.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the component. |
hidden | Boolean | Whether the component is hidden. Default: false . |
max | Number | The maximum number allowed. |
min | Number | The minimum number allowed. |
required | Boolean | Whether the component is marked as required. Default: true . |
step | Number | The interval between valid values. Default: 1 . |
value | Number | The value of the input. |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the value of the quantity
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the quantity
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | Must be one of number-float , number-integer |
label required | String |
required required | String |
help_text | String |
min required | Number |
max required | Number |
step required | Number |
Anchor to Select from choice listSelect from choice list
Use this component to let users select choices from a list.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
choices | Object[] | The list of options to choose from. |
disabled | Boolean | Whether the input is disabled. Default: false . |
required | Boolean | Whether the component is marked as required. Default: true . |
selected | String[] | A collection of selected choices. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the choices and selected values of the sizes
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the sizes
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | Must be one of select-single , select-multiple |
label required | String |
required required | String |
help_text | String |
choices required | Array: each item must contain label: String & value: String |
Anchor to BudgetBudget
Use this component to let users set budget amounts.
The currency property is required on the preload API call.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
amount | Numeric String | The budget amount |
currency* | CurrencyCode | The currency to be used for the budget (set by the preload endpoint). |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the amount. |
max_amount | Numeric String | The maximum budget amount |
min_amount | Numeric String | The minimum budget amount |
required | Boolean | Whether the component is marked as required. Default: true . |
type | String | The type of budget (daily or lifetime ). |
use_daily_budget | Boolean | Whether the user can enter a daily budget. Default: false . |
use_lifetime_budget | Boolean | Whether the user can enter a lifetime budget. Both this and use_daily_budget can be checked, and at least one of them must be checked. Default: false . |
use_total_budget (deprecated) | Boolean | Whether the user can enter a total budget. Both this and use_daily_budget can be checked, and at least one of them must be checked. Default: false . |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the amount, currency, help text, range start, range end and scheduling of budget
the field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the budget
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | budget-schedule |
label required | String |
required required | String |
help_text | String |
use_scheduling | Boolean |
use_end_date | Boolean |
use_daily_budget required | Boolean |
use_lifetime_budget required | Boolean |
Anchor to ScheduleSchedule
Use this component to let users provide a start and end date.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the component. |
end_time | Date | The user's selected end date. |
start_time | Date | The user's selected start date. |
use_end_date | Boolean | Whether the user can select an end date (in addition to a start date). Default: false . |
required | Boolean | Whether the component is marked as required. Default: true . |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below hides the end date of the start_at
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the start_at
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | schedule |
label required | String |
required required | String |
help_text | String |
use_end_date required | Boolean |
Anchor to Product selectionProduct selection
Use this component to let the user select one or more products and product images.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the resource picker. |
max_resources | Number | The maximum number of selected resources allowed. |
min_resources | Number | The minimum number of selected resources allowed. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | Product[] | An array of selected resources. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Product typeProduct type
Name | Type | Description |
---|---|---|
id | String | The product's ID. |
images | {src: String; id?: String}[] | The product's images. |
image_url (deprecated) | String | The product's image. Note: Use images property to allow users to select product images. |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the help text, maximum selected resources allowed and value of the products
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the products
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | product-picker |
label required | String |
required required | Boolean |
help_text | String |
allow_product_image_selection required | Boolean |
allow_uploaded_image_as_product_image required | Boolean |
allow_free_image_as_product_image required | Boolean |
min_resources | Number |
max_resources | Number |
min_image_select_per_product | Number |
max_image_select_per_product | Number |
Anchor to Discount selectionDiscount selection
Use this component to let the user select one or more discounts.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the resource picker. |
max_resources | Number | The maximum number of selected resources allowed. |
min_resources | Number | The minimum number of selected resources allowed. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | Object[] | An array of selected resources. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below hides the end date of the start_at
field that's defined in your Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the discount
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | discount-picker |
label required | String |
required required | Boolean |
help_text | String |
min_resources | Number |
max_resources | Number |
Anchor to Image selectionImage selection
Use this component to let the user either upload images to their shop or select images from their shop.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
help_text | String | The help text that's displayed under the resource picker. |
max_resources | Number | The maximum number of selected resources allowed. |
min_resources | Number | The minimum number of selected resources allowed. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | {src: String; id: String, altText: String, originalSrc (deprecated): String}[] | An array of selected resources. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the help text, maximum selected resources allowed and value of the featured_images
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the featured_images
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | image-picker |
label required | String |
required required | Boolean |
help_text | String |
min_resources | Number |
max_resources | Number |
allow_free_images required | Number |
alt_text_required required | Number |
Anchor to TypeaheadTypeahead
Use this component to allow users to quickly search for items from a list.
The typeahead component is populated by the dynamic standalone endpoint when the user interacts with the component.
Anchor to Dynamic standalone endpoint JSON schemaDynamic standalone endpoint JSON schema
To learn more about the dynamic standalone endpoint, refer to the marketing activity endpoints.
Anchor to Endpoint JSON propertiesEndpoint JSON properties
The JSON representation of this component, used for marketing activity endpoints, is the following:
Name | Type | Description |
---|---|---|
field_name | String | The name of the field, specified when you create the form. |
disabled | Boolean | Whether the input is disabled. Default: false . |
placeholder | String | The hint text to display. |
required | Boolean | Whether the component is marked as required. Default: true . |
value | Object[] | A collection of selected choices. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to Preload endpoint JSON output examplePreload endpoint JSON output example
The example JSON below defines the value of the colours
field defined using the Partner Dashboard.
To learn more about the preload endpoint, refer to the marketing activity endpoints.
Anchor to Create or update JSON input exampleCreate or update JSON input example
The example below includes Shopify's response to your app with the user-provided value for the colours
field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Anchor to Dynamic standalone endpoint JSON output exampleDynamic standalone endpoint JSON output example
The example JSON below defines the options of the colours
field defined using the Partner Dashboard.
To learn more about the dynamic standalone endpoint, refer to the marketing activity endpoints.
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | type-ahead |
label required | String |
required required | Boolean |
help_text | String |
placeholder required | String |
Anchor to Title and body display textTitle and body display text
Use this component to provide extra information to the user about the task that they're completing.
The title and body display text component is configured using the Partner Dashboard. It can't be set on preload and is not included in form submission.
Anchor to Component propertiesComponent properties
Name | Type | Description |
---|---|---|
title | String | The section title. |
body | String | The section body.Supports relative or secure HTTPS absolute links using markdown. For example:Click here to set up your account. or Read more about account setup. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | paragraph |
heading | String |
body | String |
Anchor to DividerDivider
Use this component to group related components into sections.
The divider component is configured in the Partner Dashboard by hovering between components and providing a section title. It can't be set on preload and is not included in form submission.
Anchor to Component propertiesComponent properties
Name | Type | Description |
---|---|---|
title | String | The section title. |
hidden | Boolean | Whether the component is hidden. Default: false . |
Anchor to CLI configurationCLI configuration
To configure this component in your extension TOML, add a fields
item entry with the following:
Name | Type |
---|---|
ui_type required | divider |
title required | String |