Skip to main content

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.


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.

{
"form_data": {
"<field_name>": {
"<property_key>": "<property_value>"
}
}
}

For the dynamic standalone endpoint, responses from your app include component_data at the top level. Refer to the typeahead component for more information.

{
"component_data": {
"options": [{"label": "<option_label>", "value": "<option_value>"}]
}
}

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.

{
...
"properties": {
"<field_name>": "<value>"
}
}

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

[[extensions]]
type = "marketing_activity"
name = "My Marketing Activity"
handle = "first-marketing-activity"
title = "Amazing Marketing Activity"
description = "Create an advertisement"
api_path = "/marketing_activities"
tactic = "ad"
marketing_channel = "social"
referring_domain = "example.com"

[[extensions.preview_data.types]]
label = "Desktop"
value = "desktop"

[[extensions.preview_data.types]]
label = "Mobile"
value = "mobile"

[[extensions.fields]]
name = "budget_id"
ui_type = "budget-schedule"
required = true
label = "Enter a budget for the ad"
use_daily_budget = true
use_lifetime_budget = false
use_scheduling = false
use_end_date = false

[[extensions.fields]]
name = "image_id"
ui_type = "image-picker"
required = true
label = "Add images"
help_text = "Select your images"
min_resources = 0
max_resources = 3
allow_free_images = true
alt_text_required = true

For every component in fields, regardless of the type, the following subfields are mandatory:

SubfieldDescription
name requiredThe API identifier. Use snake_case: lowercase letters, numbers, and underscores only.
ui_type requiredThe 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.


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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the component.
hiddenBooleanWhether the component is hidden. Default: false.
max_lengthNumberThe maximum number of characters allowed.
min_lengthNumberThe minimum number of characters allowed.
placeholderStringThe hint text to display.
requiredBooleanWhether the component is marked as required. Default: true.
valueStringThe 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.

{
"form_data": {
"ad_title": {
"help_text": "Think of something creative!",
"value": "Welcome to John's apparel store."
}
}
}

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.

{
...
"properties": {
"ad_title": "Welcome to John's crazy apparel store."
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_type requiredMust be one of text-single-line, text-email, text-tel, text-url
label requiredString
required requiredBoolean
help_textString
placeholderString
min_length requiredNumber
max_length requiredNumber

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the component.
hiddenBooleanWhether the component is hidden. Default: false.
max_lengthNumberThe maximum number of characters allowed.
min_lengthNumberThe minimum number of characters allowed.
placeholderStringThe hint text to display.
requiredBooleanWhether the component is marked as required. Default: true.
valueStringThe 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.

{
"form_data": {
"ad_body": {
"help_text": "Include a lot of information about your product.",
"value": "This shirt is the best.\n\nIt's made with high quality materials."
}
}
}

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.

{
...
"properties": {
"ad_body": "These shorts are the best.\n\nThey're made with quality materials."
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_type requiredtext-multi-line
label requiredString
required requiredBoolean
help_textString
placeholder requiredString
min_length requiredNumber
max_length requiredNumber

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the component.
hiddenBooleanWhether the component is hidden. Default: false.
maxNumberThe maximum number allowed.
minNumberThe minimum number allowed.
requiredBooleanWhether the component is marked as required. Default: true.
stepNumberThe interval between valid values. Default: 1.
valueNumberThe 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.

{
"form_data": {
"quantity": {
"value": 1
}
}
}

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.

{
...
"properties": {
"quantity": 10
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_type requiredMust be one of number-float, number-integer
label requiredString
required requiredString
help_textString
min requiredNumber
max requiredNumber
step requiredNumber

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
choicesObject[]The list of options to choose from.
disabledBooleanWhether the input is disabled. Default: false.
requiredBooleanWhether the component is marked as required. Default: true.
selectedString[]A collection of selected choices.
hiddenBooleanWhether 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.

{
"form_data": {
"sizes": {
"choices": [
{"label": "Small", "value": "sm"},
{"label": "Medium", "value": "md", "disabled": true},
{"label": "Large", "value": "lg"}
],
"selected": ["sm", "lg"]
}
}
}

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.

{
...
"properties": {
"sizes": ["sm"]
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequiredMust be one of select-single, select-multiple
label requiredString
required requiredString
help_textString
choices requiredArray: each item must contain label: String & value: String

Use this component to let users set budget amounts.

Note

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
amountNumeric StringThe budget amount
currency*CurrencyCodeThe currency to be used for the budget (set by the preload endpoint).
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the amount.
max_amountNumeric StringThe maximum budget amount
min_amountNumeric StringThe minimum budget amount
requiredBooleanWhether the component is marked as required. Default: true.
typeStringThe type of budget (daily or lifetime).
use_daily_budgetBooleanWhether the user can enter a daily budget. Default: false.
use_lifetime_budgetBooleanWhether 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)BooleanWhether 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.
hiddenBooleanWhether 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.

{
"form_data": {
"budget": {
"amount": 5,
"currency": "CAD",
"help_text": "Your shop will perform best with a $20 daily budget."
}
}
}

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.

{
...
"properties": {
"budget": {
"amount": 20,
"currency": "CAD",
"type": "daily"
}
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequiredbudget-schedule
label requiredString
required requiredString
help_textString
use_schedulingBoolean
use_end_dateBoolean
use_daily_budget requiredBoolean
use_lifetime_budget requiredBoolean

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the component.
end_timeDateThe user's selected end date.
start_timeDateThe user's selected start date.
use_end_dateBooleanWhether the user can select an end date (in addition to a start date). Default: false.
requiredBooleanWhether the component is marked as required. Default: true.
hiddenBooleanWhether 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.

{
"form_data": {
"start_at": {
"range_start": "2019-01-01T00:00:00.000Z",
"use_end_date": false
}
}
}

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.

{
...
"properties": {
"start_at": {
"start_time": "2019-01-01T00:00:00.000Z",
}
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequiredschedule
label requiredString
required requiredString
help_textString
use_end_date requiredBoolean

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the resource picker.
max_resourcesNumberThe maximum number of selected resources allowed.
min_resourcesNumberThe minimum number of selected resources allowed.
requiredBooleanWhether the component is marked as required. Default: true.
valueProduct[]An array of selected resources.
hiddenBooleanWhether the component is hidden. Default: false.

NameTypeDescription
idStringThe product's ID.
images{src: String; id?: String}[]The product's images.
image_url(deprecated)StringThe 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.

{
"form_data": {
"products": {
"help_text": "Choose products that are featured on your home page.",
"max_resources": 3,
"value": [
{
"id": "gid://shopify/Product/5",
"images": [
{
"src": "https://shopify.com/images/1"
}
]
}
]
}
}
}

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.

{
...
"properties": {
"products": [
{
"id": "gid://shopify/Product/5",
"image_url": "https://cdn.shopify.com/s/files/1",
"title": "Blue swim shorts",
},
{
"id": "gid://shopify/Product/6",
"image_url": null,
"title": "Straw hat",
}
]
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequiredproduct-picker
label requiredString
required requiredBoolean
help_textString
allow_product_image_selection requiredBoolean
allow_uploaded_image_as_product_image requiredBoolean
allow_free_image_as_product_image requiredBoolean
min_resourcesNumber
max_resourcesNumber
min_image_select_per_productNumber
max_image_select_per_productNumber

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the resource picker.
max_resourcesNumberThe maximum number of selected resources allowed.
min_resourcesNumberThe minimum number of selected resources allowed.
requiredBooleanWhether the component is marked as required. Default: true.
valueObject[]An array of selected resources.
hiddenBooleanWhether 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.

{
"form_data": {
"discount": {
"help_text": "Choose a discount for this activity.",
"max_resources": 1,
"value": [
{
"id": "gid://shopify/PriceRule/1"
}
]
}
}
}

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.

{
...
"properties": {
"discount": [
{
"id": "gid://shopify/PriceRule/1",
"title": "BLACKFRIDAY10",
"summary": "10% off entire order",
"features": [],
"status": "ACTIVE"
}
]
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequireddiscount-picker
label requiredString
required requiredBoolean
help_textString
min_resourcesNumber
max_resourcesNumber

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
help_textStringThe help text that's displayed under the resource picker.
max_resourcesNumberThe maximum number of selected resources allowed.
min_resourcesNumberThe minimum number of selected resources allowed.
requiredBooleanWhether the component is marked as required. Default: true.
value{src: String; id: String, altText: String, originalSrc (deprecated): String}[]An array of selected resources.
hiddenBooleanWhether 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.

{
"form_data": {
"featured_images": {
"help_text": "Choose an image for this activity.",
"max_resources": 3,
"value": [
{
"id": "gid://shopify/ShopImage/1",
"alt_text": "Blue sweater",
"src": "https://cdn.myshopify.io/s/files/1/0000/0001/files/googlee.jpg"
},
{
"id": "4289",
"alt_text": "Black friday!",
"src": "https://burst.shopifycdn.com/photos/i-heart-black-friday.jpg"
}
]
}
}
}

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.

{
...
"properties": {
"featured_images": [
{
"id":"gid://shopify/ShopImage/1",
"src":"https://cdn.shopify.com/s/files/1/1/1/files/blue_shorts.png?v=1517010629",
"alt_text":"Blue shorts"
},
{
"id":"gid://shopify/ShopImage/2",
"src":"https://cdn.shopify.com/s/files/1/1/1/files/red_shorts.png?v=1517010629",
"alt_text":"Red shorts"
}
]
}
}

To learn more about the create or update endpoint, refer to the marketing activity endpoints.

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

NameType
ui_typerequiredimage-picker
label requiredString
required requiredBoolean
help_textString
min_resourcesNumber
max_resourcesNumber
allow_free_images requiredNumber
alt_text_required requiredNumber

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.

Anchor to Dynamic standalone endpoint JSON schemaDynamic standalone endpoint JSON schema

{
"field_data": {
"options": [{"label": "<option_label>", "value": "<option_value>"}]
}
}

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:

NameTypeDescription
field_nameStringThe name of the field, specified when you create the form.
disabledBooleanWhether the input is disabled. Default: false.
placeholderStringThe hint text to display.
requiredBooleanWhether the component is marked as required. Default: true.
valueObject[]A collection of selected choices.
hiddenBooleanWhether 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.

{
"form_data": {
"colours": {
"value": [
{"label": "Red", "value": "red"},
{"label": "Blue", "value": "blue"},
{"label": "Yellow", "value": "yellow"}
]
}
}
}

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.

{
...
"properties": {
"colours": [
{"label": "Red", "value": "red"},
{"label": "Blue", "value": "blue"}
]
}
}
}

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.

{
"field_data": {
"options": [
{"label": "Red", "value": "red"},
{"label": "Blue", "value": "blue"},
{"label": "Yellow", "value": "yellow"}
]
}
}

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

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

NameType
ui_typerequiredtype-ahead
label requiredString
required requiredBoolean
help_textString
placeholder requiredString

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.

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.

Anchor to Component propertiesComponent properties

NameTypeDescription
titleStringThe section title.
bodyStringThe 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.
hiddenBooleanWhether the component is hidden. Default: false.

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

NameType
ui_typerequiredparagraph
headingString
bodyString

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.

Anchor to Component propertiesComponent properties

NameTypeDescription
titleStringThe section title.
hiddenBooleanWhether the component is hidden. Default: false.

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

NameType
ui_typerequireddivider
titlerequiredString

Was this page helpful?