Marketing activity 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, see Create a form from your Partner Dashboard.

Overview

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

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. See the typeahead component for more information.

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

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.

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

Single line of text

Use this component to let merchants 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.

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

To learn more about the preload endpoint, see the marketing activity endpoints.

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.

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

To learn more about the create or update endpoint, see 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.

{
  "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, see the marketing activity endpoints.

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.

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

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

Number

Use this component to let merchants 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.

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

To learn more about the preload endpoint, see the marketing activity endpoints.

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.

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

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

Select from choice list

Use this component to let merchants 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.

Preload 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, see the marketing activity endpoints.

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.

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

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

Budget

Use this component to let merchants set budget amounts.

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.

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.

{
  "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, see the marketing activity endpoints.

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.

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

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

Schedule

Use this component to let merchants 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.
end_time Date The merchant's selected end date.
range_start Date The earliest selectable date.
range_end Date The latest selectable date.
required Boolean Whether the component is marked as required. Default: true.
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.

Preload endpoint JSON output example

The example JSON below defines the range start and 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, see the marketing activity endpoints.

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.

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

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

Product selection

Use this component to let the merchant 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.

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

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, see the marketing activity endpoints.

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.

{
  ...
  "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, see the marketing activity endpoints.

Discount selection

Use this component to let the merchant 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.

Preload endpoint JSON output example

The example JSON below defines the help text, maximum selected resources allowed and value of the discount field defined using the 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, see the marketing activity endpoints.

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.

{
  ...
  "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, see the marketing activity endpoints.

Image selection

Use this component to let the merchant 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 Object[] An array of selected resources.

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.

{
  "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"
        }
      ]
    }
  }
}

To learn more about the preload endpoint, see the marketing activity endpoints.

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.

{
  ...
  "properties": {
    "featured_images": [
      {
        "id":"gid://shopify/ShopImage/1",
        "original_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",
        "original_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, see the marketing activity endpoints.

Typeahead

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

Dynamic standalone endpoint JSON schema

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

To learn more about the dynamic standalone endpoint, see 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.

Preload 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, see the marketing activity endpoints.

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.

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

To learn more about the create or update endpoint, see 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.

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

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

Title and body display text

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

Component properties

Name Type Description
title String The section title.
body String The section body.
Supports relative or secured absolute links using markdown. For example, "Click [here](/admin/app) to setup your account" or "Read more about [account setup](https://app.com)."

Divider

Use this component to group related components into sections.

Component properties

Name Type Description
title String The section title.

Sign up for a Partner account to get started.

Sign up