Marketplace sellerId

Here before January 2023?

We've updated our documentation in advance of some changes expected to rollout to production in January 2023. If you're reviewing our documentation beforehand, you might notice the below not working - that's because it's not there yet!

As this is in active development, this is subject to change at CitrusAd's discretion.

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