Standard product sync
Once your catalog is created, you are able to sync products to it. The example below outlines a standard context to sync products:
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",
"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"
]
}
]
}
If successful, the following object will be returned:
{
"catalogProducts": [
{
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"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"
],
"groups": [],
"profit": null
}
]
}
In this context, empty or null values for groups and profit can be ignored.
Syncing location information
You are also able to synchronise filters for various locations your products are in store. This is useful for store/location level optimisation of your product information.
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",
"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","location:123","location:ABC"
]
}
]
}
If successful, the following object will be returned:
{
"catalogProducts": [
{
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"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",
"location:123",
"location:ABC"
],
"groups": [],
"profit": null
}
]
}
Syncing HFSS information
In your product sync, you will need to send a filter of hfss:true or hfss:false. This enables CitrusAd to filter our interface appropriately.
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",
"inventory": 50,
"price": "19.99",
"tags": [
"imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"hfss:true","category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
]
}
]
}
Need to learn more about HFSS?
Review the UK Government's publication here: https://www.gov.uk/government/publications/restricting-promotions-of-products-high-in-fat-sugar-or-salt-by-location-and-by-volume-price/restricting-promotions-of-products-high-in-fat-sugar-or-salt-by-location-and-by-volume-price-implementation-guidance
Syncing multiple products
If you are syncing multiple products, you can sequence up to 100 per request.
An example context for syncing two products is outlined below:
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",
"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"
}
]
}
If successful, the following object will be returned:
{
"catalogProducts": [
{
"gtin": "23556578965543",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"price": 19.99,
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"groups": [],
"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"
],
"inventory": 50,
"profit": 1.50,
"tags": [
"Natural",
"Lasting",
"Dry Skin",
"Beige"
]
},
{
"gtin": "23556578965736688",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"price": 8.50,
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"groups": [],
"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"
],
"inventory": 26,
"profit": 0.50,
"tags": [
"Pantry",
"BreakfastFoods",
"Cereals",
"Kelloggs"
]
}
]
}
Updating product inventory
To update a product's inventory, you will need to re-sync the product with CitrusAd. In your sync, flag the product's inventory to 0. An example is outlined below:
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",
"inventory": 0,
"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"
]
}
]
}
Retrieving products
Once you have a product in your catalog, you may wish to retrieve the current information it at a later time.
To do this, you can make a GET http request with the url form of v1/catalog-products/catalogId/<PRODUCT_CODE>. The endpoint is capable of accepting one product code per request. A placeholder request is outlined below:
GET $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
You should receive the current information ingested in the CitrusAd system for the product code. An example is below
Pushing a product update is not instant in the CitrusAd system, it can take a short amount of time for CitrusAd to fully ingest a product update. Do not be concerned if a product's information is not instantly updated when retrieving details.
Deleting products
Once you have a product in your catalog, you may wish to delete it at a later time.
To do this, you can make a DELETE http request with the url form of v1/catalog-products/catalogId/<PRODUCT_CODE>. The endpoint is capable of accepting one product code per request. A placeholder request is outlined below:
DELETE $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
It can take 30 minutes to one hour to process the product deletion.
If a product is out of stock, it should be set to 0 in the inventory, NOT deleted. Deleting a product will remove the ability for advertisers to select it in the CitrusAd platform to advertise automatically when it is back in stock.
In the event the product is not found, it has likely not been ingested into the CitrusAd system.