Marketplaces Guide

This guide is intended for marketplaces that are interested in offering or enhancing a marketing solution to drive additional purchases and grow revenue streams for their merchants. In this guide, you’ll learn how to use the NextRoll API to easily onboard merchants and run marketing campaigns across a vast selection of channels and inventory sources.

Getting to know the NextRoll API

Before you start building your integration, it helps to have a basic understanding of the NextRoll API:

Get Started with the NextRoll API will help you make your first API call.

Get to know NextRoll provides an overview of the object structure and defines common terminology.

Definition Of Terms

We’ll make references to the following terms that are specific to this guide:

Marketplace

A service provider that hosts multiple businesses that want to advertise independent of each other

Merchant

A business that participates in the Marketplace that will advertise independent of other businesses

Parent Advertisable

The account, also known as Advertisable, that owns the Pixel that is placed on the Marketplace’s website

Merchant Advertisable

An account or Advertisable that belongs to a merchant

Overview

A single Organization contains all of your merchant Advertisables. The overarching Parent Advertisable owns the Pixel. This Pixel is placed on your site and enables you to identify which merchant a page view belongs to. When you onboard a merchant, you will create a new Advertisable for them.

If this setup doesn’t quite match your needs, one of these Variations might.

To begin, you’ll start the initial setup:

  1. Organization Setup

  2. Pixel Setup

After that, merchants will go through the following lifecycle:

  1. Onboarding a Merchant

  2. Campaign Management

  3. Offboarding a Merchant

Organization Setup

After you successfully created a user account an Organization and Advertisable are automatically generated for you. This first Advertisable will serve as your Parent Advertisable.

To create merchant accounts , therefore merchant-specific Advertisables, you’ll need your Organization EID. This can be found in the eid field returned by GET /api/v1/organization/get.

Pixel Setup

The Pixel is a snippet of JavaScript that you place on all of your webpages and can be configured by setting JavaScript variables.

While most users place a Pixel for each account on the respective website, Marketplaces operate on a single site and therefore install one Pixel from the Parent Advertisable. Marketplace Mappings then allow differentiating between the individual merchants.

To retrieve the Pixel using the API:

  1. Call GET /api/v1/organization/get_advertisables to retrieve the list of Advertisables (there should be only one at this point). You’ll need the value of the eid field for the next step

  2. Call GET /api/v1/advertisable/get_pixel and specify the advertisable parameter.

You should then place the JavaScript snippet on your website, right before the closing </body> HTML tag.

If each merchant has their own website, see the Web Site per Merchant variant.

Marketplace Mapping

Required

Since you are deploying a single pixel but running multiple Advertisables, we need to make sure that we can identify which merchant was visited.

On merchant pages that are running marketing programs, please set the adroll_shop_id global JavaScript variable to your merchant identifier. This identifier should match the one you configure in the Configure Marketplace Mapping step. If you don’t specify the marketplace mapping, the visits will be attributed to the Parent Advertisable.

For example:

<script type="text/javascript">
  adroll_shop_id = "Tv4xh0cB50VCdCeHzb3csA"; // Your ID for the merchant
</script>

Enhanced Conversion Tracking

Optional

To enable revenue tracking or the tracking of custom values such as order IDs, user IDs, and more please review Setting Up Enhanced Conversion Tracking.

For example:

<script type="text/javascript">
  adroll_conversion_value = X;
  adroll_currency = "USD";
  adroll_custom_data = {"ORDER_ID": "W", "USER_ID": "Z"};
</script>

Cross-Device Targeting

Optional (Recommended)

To enhance cross-device targeting and attribution, set adroll_email and/or adroll_user_identifier when calling the Pixel. The value of adroll_email is the plaintext or MD5 hashed email address for the user (if you have one). The value of adroll_user_identifier is your custom identifier for the user (if you have one).

For example:

<script type="text/javascript">
  adroll_email = "test@example.com";
  adroll_user_identifier = "C9470D4D067EF94A7721BA";
</script>

Onboarding a Merchant

The following steps are needed to onboard a new merchant.

Creating an Account

First, you’ll create an Account for the merchant which establishes an Advertisable EID that will be used for subsequent API calls.

Call POST /api/v1/advertisable/create with the following parameters:

  • organization — EID for your Organization

  • name — Name of the merchant. This can be returned in the GraphQL Reporting API when generating reports

  • country_code - ISO-3166 2-Letter country code the Advertisable is registered in

Configure Marketplace Mapping

We need to establish a mapping between your internal ID for the merchant sent through the Pixel and the Advertisable you just created.

Call POST /api/v1/marketplace/create with the following parameters:

  • source_advertisable — EID for your Parent Advertisable

  • dest_advertisable — EID for the Merchant Advertisable that you created in the previous step

  • shop_id — Your internal ID for the merchant that matches what will be sent in the adroll_shop_id Pixel parameter

Adding a Product Feed

If you plan to run ads that contain product recommendations, namely Dynamic Creative, you’ll need to set up a product feed for the Merchant. If you don’t have a product feed in a standard format, we can work with you to configure our system to parse your feed.

Call POST /api/v1/feed/autoconfigure with the feed URL we can access on an ongoing basis. We will automatically recognize the feed and configure the rest.

We will periodically re-fetch each feed to update the product catalog. Ideally, you will host your feeds at a publicly accessible URL, but we can fetch them using (S)FTP if needed.

See Setup Product Feeds for Dynamic Creative for additional information.

Create Ads

Depending on where you’ll run campaigns, review these guides for how to create ads:

When creating ads, be sure to keep track of the EIDs returned. You’ll need to specify them when launching the campaign.

Defining Audiences

Audiences or segments represent a set of people who will be targeted or excluded from Campaigns. There are many different types of Audiences, please review Creating Audiences to learn more about creating them. The most common audience type is based on the URLs visited. These URL based audiences can be used to target visitors to specific pages such as a cart or conversion page.

Launching a Campaign

Once you’ve successfully created your ads and audiences, you can create a Campaign by calling POST /activate/api/v2/campaign. By default, it will start spending right away, but you can also specify a start date.

For example, this call will create a campaign with one AdGroup containing a single ad and audience:

{
  "advertisable_eid": "MY_ADVERTISABLE_EID",
  "name": "My First Campaign",
  "objective": "convert",
  "budget_settings": {
    "budget_type": "daily",
    "goal": 200.0
  },
  "adgroups": [
    {
      "name": "My AdGroup",
      "kpi_metric": "CPC",
      "kpi_goal": 5.0,
      "ad_type": "static",
      "ads": [
        {
          "eid": "MY_AD_EID",
          "status": "live"
        }
      ],
      "targeting_features": {
        "positive_segment_eids": [
          "MY_SEGMENT_EID"
        ]
      }
    }
  ]
}

Campaign Management

Below you can find the day to day operations of a live merchant.

Pause the Campaign

Call PUT /activate/api/v2/campaign to pause a campaign. The body of the request will look like:

{
  "status": "paused"
}

Resume the Campaign

Call PUT /activate/api/v2/campaign to resume a campaign. The body of the request will look like:

{
  "status": "live"
}

Generate Reports

You can use the GraphQL Reporting API to retrieve reporting metrics.

Example query:

query AllAdvertisables {
  advertisable {
    byEIDs(eids: ["MY_ADVERTISABLE_EID"]) {
      eid
      name
      metrics(start: "2019-12-09", end: "2019-12-10") {
        byDate {
          date
          cost
          impressions
          clicks
        }
      }
    }
  }
}

Offboarding a Merchant

To offboard a merchant, you should:

  1. Pause the Campaign

  2. Stop attributing website visits to a merchant by not setting the adroll_shop_id Pixel parameter for the merchant

Variations

Web Site per Merchant

For some marketplaces, each merchant has their own website on a different domain. If that’s your setup, you can place the Pixel attached to the merchant’s Advertisable on their website. You can also skip the Marketplace Mapping API call and setting the adroll_shop_id Pixel parameter.