Marketing activities components reference
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.
To learn how to create a form for your app, refer to Getting started with marketing activities.
How it works
Anchor link to section titled "How it works"When a merchant 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 merchant creates or updates a marketing activity, Shopify calls your app by sending the properties object with the included field names and corresponding values.
Single line of text
Anchor link to section titled "Single line of text"Use this component to let merchants provide text input when the expected input is short.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the ad_title field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
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.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the ad_body field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Use this component to let merchants provide number input.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the quantity field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Select from choice list
Anchor link to section titled "Select from choice list"Use this component to let merchants select choices from a list.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the sizes field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Use this component to let merchants set budget amounts.
Component properties
Anchor link to section titled "Component properties"| 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 merchant can enter a daily budget. Default: false. |
use_lifetime_budget |
Boolean | Whether the merchant 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 merchant 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 merchant-provided value for the budget field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Use this component to let merchants provide a start and end date.
Component properties
Anchor link to section titled "Component properties"| 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 merchant's selected end date. |
start_time |
Date | The merchant's selected start date. |
use_end_date |
Boolean | Whether the merchant 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 merchant-provided value for the start_at field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Product selection
Anchor link to section titled "Product selection"Use this component to let the merchant select one or more products and product images.
Component properties
Anchor link to section titled "Component properties"| 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 merchants 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 merchant-provided value for the products field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Discount selection
Anchor link to section titled "Discount selection"Use this component to let the merchant select one or more discounts.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the discount field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Image selection
Anchor link to section titled "Image selection"Use this component to let the merchant either upload images to their shop or select images from their shop.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-provided value for the featured_images field.
To learn more about the create or update endpoint, refer to the marketing activity endpoints.
Use this component to allow merchants to quickly search for items from a list.
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.
Component properties
Anchor link to section titled "Component properties"| 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 merchant-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.
Title and body display text
Anchor link to section titled "Title and body display text"Use this component to provide extra information to the merchant about the task that they're completing.
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. |
Use this component to group related components into sections.
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. |