Manage Product Details in Your Catalog Using APIs
Retailers can manage product details in their catalog using various API endpoints. These APIs allow you to:
- Update product inventories
- Delete products from the catalog
- Retrieve detailed information about products
Update Product Inventory
To update a product's inventory, re-sync the product with CitrusAd and set its inventory to zero. Retailers usually perform these updates daily to reflect changes such as:
- Product name updates
- Inventory status. If a product's inventory is set to zero, it indicates that the product is sold out. However, new inventory may arrive the next day.
Request Parameters
The following are the query and body parameters:
Query Parameter
| Object | Type | Description |
|---|---|---|
| teamId | string, optional | ID of your team. If a teamId is not provided, it will default to the teamId specified in the authentication. |
Body Parameter
| Object | Type | Description |
|---|---|---|
| catalogId | string, required | Identifier for the catalog to which the product belongs. You can get the catalogID from the Epsilon's Retail Media UI or from the retailer. |
| gtin | string, required | Global Trade Item Number (GTIN) for the product. |
| inventory | number, optional | Inventory count for the product. |
| price | number, optional | Price of the product. |
| categoryHierarchy | array of strings, optional | Hierarchy of categories to which the product belongs. |
| tags | array of strings, optional | Tags associated with the product. |
| filters | array of strings, optional | Filters applied to the 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",
"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"
]
}
]
}
Delete Products from Your Catalog
Once a product is in your catalog, you may need to delete it at a later time. To delete a product, follow the steps below.
Request Parameters
The endpoint accepts one product code per request, which is typically your GTIN ID. To delete a product, make a DELETE HTTP request as follows:
DELETE $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
Processing Time
It can take between 30 minutes to one hour to process the product deletion.
Important
If a product is out of stock, set its inventory to 0 instead of deleting it. Deleting a product removes the ability for advertisers to select it in the CitrusAd platform, even when it is back in stock.
Error Handling
If the product is not found, it likely means the product has not been ingested into the CitrusAd system.
Retrieve Product Details
You may need to retrieve the current information of a product in your catalog at a later time. To do this, you can send a GET HTTP request as follows:
GET $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
| Object | Type | Description |
|---|---|---|
| catalogId | string, required | Identifier for the catalog to which the product belongs. You can get the catalogID from the Epsilon's Retail Media UI or from the retailer. |
| Prooduct code | string, required | This is typically Global Trade Item Number (GTIN) of the product. |
You should receive the current information ingested in the CitrusAd system for the specified product code.
Note
Product updates are not processed instantly in the CitrusAd system. It may take some time for CitrusAd to fully ingest and reflect the update. Do not be concerned if the product information is not immediately updated when retrieved.
Updated 4 months ago