Reference
String | Description | Required or Optional |
adId | The Ad ID. This field should be populated if this order item has been bought as a result of a click on an ad. | Optional |
adIds | The Ad IDs. This field should be populated if an explicit association between order items and ad ids can't be provided. This field is used to provide the association at order level. | Optional |
Api Key | This is your Api Key. Your Api Key is used to identify and authorise the Retailer team. | Required |
bannerSlotIds | This defines the ids of the Banner Ads slots that are available on the retailer website. Banner Ad slots are defined in content standards. Content standards are provided by retailers. | Required for Banner Ads |
catalogs | The catalogs being created | Required |
catalogId | The id of the catalog the product belongs to. This is required to bind a product to a catalog. | Required |
citrusDiscountAmount | The amount of the Citrus discount that was applied to the ad. The application to an ad of both a discount amount and additional constraints can cause the Citrus discount value to be less than the maximum value of the original ad. | Required for Discounts |
contentStandardId | Defines the content standard to use in Banner Ad generation. | Required for Banner & Email Ads |
context | The context of the ad served | Required |
currentCartItems | This field is populated with information about items that the user has already added to their cart. | Required for Sample, Substitution, and Discount campaigns |
customerId | The id of the customer that has created the order. | Optional |
groups | A list of traits of the product. Must be human readable Can be things such as: brand, category, style, demographic, ect. | Optional |
GTIN | Global Trade Item Number. A globally-unique 14-digit number used to identify trade items. ​ This can be substituted for any unique code or SKU used in your back end. | Required |
filters | filters associated with the request | Required |
id | This is the ID of the content you are pushing to Citrus. This can be a catalog id or order id. This is individual to each individual item pushed. | N/A |
inventory | The number of available items of this product. | Optional |
imageUrl | The URL of the image of the product | Required |
maxNumberOfAds | This is the maximum number of ads that Citrus generates. If advertisers have not provided enough requests for ad placements, the number of ads provided will not reach the number defined here. Must be greater than 0. | Required |
name | The name of your catalog. If you are importing multiple catalogs your advertisers will be able to see these catalog names when creating campaigns | Required |
orderDate | The date of the order. | Required |
orderItems | The items included in the order being pushed to Citrus | Required |
orders | The type of object being pushed to Citrus. In this case it is orders | N/A |
pageType | This field determines the type of ad that is to be returned. Home, Category, Search, and Specials fall into the display ad category which is applicable when user is browsing the website and looking for products to add to cart. | Required |
Price | The price of the product | Optional |
productFilters | This field is optional. This is an array of string arrays that includes product filter ids previously sent to Citrus when catalog product information was sent to Citrus. This makes it possible for the ad requester to narrow down the ads returned so that the ads that are returned are only the ones that match the filter. An example of a filter is [["a", "b"], ["c", "d"]] or (a && b) || (c && d). These can be interpreted as ("A and B or C and D"). | Optional, depending upon pageType. If the pageType is category, this is required. |
productName | The name of the product. | Required |
profit | Typical monetary profit of the product | Optional |
quantity | The quantity of the product purchased | Required |
regularUnitPrice | The regular price of the item added to cart | Required |
searchTerm | The search term entered by the customer. This is used for filtering purposes. | Required |
sessionId | This is a generated id that you control that identifies a user's session. Citrus can use this for purchase attribution. | Required |
substitutedFor | The GTIN of the product that the item was substituted for. | Required for Substitutions |
substitutedProductGtin | If the pageType is "substitutions", this field is mandatory. If the product is being substituted in the picking process, this product identifier should be provided so that you can receive ads for the replacement product. | Optional |
tags | A string array of tags associated with the product. | Optional |
teamId | Your retailer teamId, this is used to identify the orders are coming from your team | Optional |
totalOrderItemPriceAfterDiscounts | The whole order item price after all applicable discounts are applied. ​ For example, if an order item contains 3 items with a price of 2.00, the value will be | Required |
Groups are applied to a catalog product. They specify traits about products that advertisers can use to create campaigns against groups of products, rather than specific products. They must be human readable. Groups could be things like: brand, category, style, demographic, etc.
An example of this would be a specific product range that share a similar trait. Such as a pair of basketball and running shoes still under the same specific product range.
{"gtin": "productStyle1-Basketball","groups": ["Brand","Shoes","Mens","ProductRangeName","Basketball"]}{"gtin": "productStyle2-Running","groups": ["Brand","Shoes","Mens","ProductRangeName","Running"]}
When creating a campaign, advertisers would then be able to specify that they want to create ads for all products that match those groups. e.g. "Brand", "Shoes", "Running" would create ads for the productStyle2-Running product, but not the productStyle1-Basketballproduct. This becomes powerful if an advertiser wishes to create ads for their entire shoe collection, they could select the groups for their brand, and their shoes.
In the above example, they would select: "Brand", "Shoes".
