Partner API

Marketplace sellerId

What is a marketplace?

Marketplaces are a unique opportunity for retailers to expand online presence as well as engage new or casual buyers with ease. Marketplaces allow smaller businesses to reach a wide variety of customers, typically shipped directly by the marketplace seller to the customer.

Marketplaces enable sellers to sell their products on a retailer’s site, increasing their product visibility to a wider audience. While retailers gain additional product offerings to sell to a wider range of customers.

In addition to monetizing your site with marketplace capabilities; retailers can also capitalise on this premium online shelf space and offer the opportunity for marketplace vendors to bid for top positions via CitrusAd through the documentation listed below.

Setting up marketplace advertisers

Once your integration enhancements are complete (detailed below), you will be able to set a Seller ID per team. This can only be done when creating a team from the retailer team, this cannot be done when editing a team or by a supplier.

There is an "Optional fields" section when creating a new team where the Seller ID can be selected. The Seller IDs able to be selected are sourced directly from your product catalog. You cannot enter a value that is not present in the product catalog.

Integration requirements

High level overview

In addition to a standard integration with CitrusAd, your integration will need to be enhanced with the below changes:

  • Implement a sellerId per product in the product catalog file or API
  • Parse ad response and render the correct seller’s offer when relevant
  • Report a sellerId per unique product when reporting orders to CitrusAd

Product catalog enhancements.

In your product catalog synchronised with Citrus, you will need to provide a sellerId per unique product code to CitrusAd.

Syncing catalog via file

You will need to add an additional column/section to your catalog file of seller_id. Every seller_id and product_code combination must be a unique row. For non marketplace products, the seller_id can be empty.

For examples, please visit Syncing catalog and product via file

Syncing catalog via API

When synchronising products via API, you will need to synchronise a sellerId per unique sellerId & gtin combination. For non marketplace products, you can omit the sellerId as it is an optional field. An example below displays synchronising 2 sellerIds for the same gtin, and a non marketplace product.

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "sellerId": "327272-sade2-3ja",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
                 "category:Grocery",
                 "Brand:Covergirl",
                 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "sellerId": "09sa-d32s--faasw",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
                 "category:Grocery",
                 "Brand:Covergirl",
                 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965738",
            "inventory": 26,
            "price": "8.50",
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "profit": "0.50"
        }
    ]
}

Ad response enhancements

When CitrusAd serves ads, a sellerId will be served if the gtin has one associated with it. This applies to all ad types, but is only relevant for ad rendering from product ads. An example product ad response is below:

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

To ensure the correct seller's offer is shown, you should read the sellerId provided by CitrusAd and display the correct seller's offer to the customer.

Order reporting enhancements

When reporting orders to CitrusAd, you will also need to specify the sellerId per unique gtin when you report orders to CitrusAd.

🚧

This step is required and cannot be missed or ads will not attribute to orders.

Syncing orders via file

You will need to add an additional column/section to your order file of seller_id. Every seller_id and product_code combination must be a unique row. For non marketplace products purchased, the seller_id can be empty.

For examples, please visit Syncing order data via file

Syncing orders via API

When synchronising orders via API, you will need to synchronise the sellerId where applicable when reporting orders. In the event the purchased product does not have a sellerId, it can be omitted.

Below is an example of an order where one product is from a marketplace seller and another is not a marketplace product:

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
       {
       "customerId": "npc-s243-ir",
        "sessionId": "5cat7-9964-4f",
        "orderDate": "2021-12-02T15:00:00Z",
        "id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00",
                  "sellerId": "10sa-3s33-j8e3"
                }
              ]
            },
          {
                  "gtin": "351998532P",
                  "quantity": 1,
                  "regularUnitPrice": "2.50",
                  "totalOrderItemPriceAfterDiscounts": "2.50"            
                }
              ]
            }
    ]
}

Migrating existing teams

If you are enhancing your integration to support marketplace sellers, there are a number of steps you or your advertisers need to take. It is important to know how products operate within the CitrusAd system.

A product with no seller ID and a product with a seller ID are two unique entities in the CitrusAd system. As such, campaigns need to be migrated to select the correct new product variant for all existing campaigns that need to be updated.

  1. Inform your CitrusAd technical account manager of your intent to enable the marketplace seller ID feature
  2. Your technical account manager should be able to ensure our internal attribution is configured to handle migrating teams
  3. Enhance product catalog with seller ID products
  4. Enhance order reporting to report seller ID
  5. If migrating existing teams, edit existing teams to specify seller ID
  6. Once a team is edited, each team's campaigns need to be edited to select the products again. This is because we need the new product with a seller ID selected in the campaign, whereas campaigns created before the team had a seller ID will not have the correct variant of the product selected.