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

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

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

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.

Single line of text

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

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

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

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.

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

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

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

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.

Number

Use this component to let users provide number input.

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

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

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.

Select from choice list

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

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

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

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.

Budget

Use this component to let users set budget amounts.

Note

The currency property is required on the preload API call.

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 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

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

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.

Schedule

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

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 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

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

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.

Product selection

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

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

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

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

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.

Discount selection

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

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

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

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.

Image selection

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

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

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

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.

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

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

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

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

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

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

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

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.

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

Name	Type	Description
title	String	The section title.
hidden	Boolean	Whether the component is hidden. Default: false.