• How it works
  • Extensions configured with Shopify CLI
  • Single line of text
  • Multiple lines of text
  • Number
  • Select from choice list
  • Budget
  • Schedule
  • Product selection
  • Discount selection
  • Image selection
  • Typeahead
  • Title and body display text
  • Divider

Marketing activities components reference

Deprecated

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.

How it works

Anchor link to section titled "How 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.

Preload endpoint JSON output schema

Anchor link to section titled "Preload 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.

Create or update JSON input schema

Anchor link to section titled "Create 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.

Extensions configured with Shopify CLI

Anchor link to section titled "Extensions 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:

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.

Single line of text

Anchor link to section titled "Single line of text"

Use this component to let users provide text input when the expected input is short.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI 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

Multiple lines of text

Anchor link to section titled "Multiple 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.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI 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

Number

Anchor link to section titled "Number"

Use this component to let users provide number input.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI 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

Select from choice list

Anchor link to section titled "Select from choice list"

Use this component to let users select choices from a list.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired 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

Budget

Anchor link to section titled "Budget"

Use this component to let users set budget amounts.

Note

The currency property is required on the preload API call.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired 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

Schedule

Anchor link to section titled "Schedule"

Use this component to let users provide a start and end date.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired schedule
label Required String
required Required String
help_text String
use_end_date Required Boolean

Product selection

Anchor link to section titled "Product selection"

Use this component to let the user select one or more products and product images.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Product type

Anchor link to section titled "Product 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired 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

Discount selection

Anchor link to section titled "Discount selection"

Use this component to let the user select one or more discounts.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired discount-picker
label Required String
required Required Boolean
help_text String
min_resources Number
max_resources Number

Image selection

Anchor link to section titled "Image selection"

Use this component to let the user either upload images to their shop or select images from their shop.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired 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

Typeahead

Anchor link to section titled "Typeahead"

Use this component to allow users to quickly search for items from a list.

Note

The typeahead component is populated by the dynamic standalone endpoint when the user interacts with the component.

Dynamic standalone endpoint JSON schema

Anchor link to section titled "Dynamic standalone endpoint JSON schema"

To learn more about the dynamic standalone endpoint, refer to the marketing activity endpoints.

Endpoint JSON properties

Anchor link to section titled "Endpoint 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.

Preload endpoint JSON output example

Anchor link to section titled "Preload 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.

Create or update JSON input example

Anchor link to section titled "Create 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.

Dynamic standalone endpoint JSON output example

Anchor link to section titled "Dynamic 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.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired type-ahead
label Required String
required Required Boolean
help_text String
placeholder Required String

Title and body display text

Anchor link to section titled "Title and body display text"

Use this component to provide extra information to the user about the task that they're completing.

Note

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.

Component properties

Anchor link to section titled "Component 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](https://example.com) to set up your account.
or
Read more about [account setup](https://example.com).
hidden Boolean Whether the component is hidden. Default: false.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired paragraph
heading String
body String

Divider

Anchor link to section titled "Divider"

Use this component to group related components into sections.

Note

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.

Component properties

Anchor link to section titled "Component properties"
Name Type Description
title String The section title.
hidden Boolean Whether the component is hidden. Default: false.

CLI configuration

Anchor link to section titled "CLI configuration"

To configure this component in your extension TOML, add a fields item entry with the following:

Name Type
ui_typeRequired divider
titleRequired String

On this page

  • How it works
  • Extensions configured with Shopify CLI
  • Single line of text
  • Multiple lines of text
  • Number
  • Select from choice list
  • Budget
  • Schedule
  • Product selection
  • Discount selection
  • Image selection
  • Typeahead
  • Title and body display text
  • Divider