Marketing activities overview

This section describes the requirements for adding a marketing activity extension to your app, and how your app works with the app extension definition and Shopify to support marketing activities.

Getting started

To add a marketing activity extension to your app, you need a development store and an app that you can extend. You can use the development store for testing while you are working on your marketing activity extension.

Set up your app to work with a marketing activity extension

  1. Add a marketing activity extension using the Partner Dashboard.
  2. Host the required endpoints on your app's domain. Shopify uses REST calls and structured JSON to communicate with your app. Make sure to verify that the request came from Shopify.
  3. Provide a preview for your marketing activities. The preview endpoint is recommended for the best experience of your app, as it allows merchants to see changes in real-time before publishing.
  4. Set up engagements for your marketing activities.
  5. Submit your extension for approval.

App extension architecture

This section describes how your app's endpoints interact with the app extension definition and with Shopify.

You define a marketing activity form by using the app extension's form builder in your Partner Dashboard. Each marketing activity extension is uniquely identified by its UUID, which is used to open the marketing activity form. Shopify calls your app's preload endpoint to render the marketing activity form. Your app is responsible for responding with form data based on the merchant’s marketing activity and the state of a merchant's shop data. Shopify also calls your app's error feedback endpoint to report whether there were problems with your marketing activity extension.

A flowchart that shows how your app works with the extension and Shopify to render the marketing activity form for the merchant.

  1. The merchant uses the app extension form to create a marketing activity.
  2. Shopify calls your app's preload endpoint.
  3. The app responds with form data.
  4. The creation form is rendered with the preview.
  5. If there is an error rendering the form, then Shopify reports this to the app's error feedback endpoint.

After a merchant publishes a marketing activity, Shopify calls your app's create endpoint to create the marketing activity. Your app is responsible for validating the form data. After the marketing activity is created, your app calls Shopify to update the status of the marketing activity using MarketingActivityUpdate.

A flowchart that shows how your app works with the extension and Shopify to publish the marketing activity and update its status.

  1. The merchant clicks to publish the marketing activity.
  2. Shopify creates the marketing activity and sends a request to the app's create endpoint
  3. The app validates the form data, publishes the marketing activity asynchronously, and updates status information using MarketingActivityUpdate.
  4. Shopify updates the marketing activity status.
  5. Shopify renders the marketing activity.

Sign up for a Partner account to get started.

Sign up