Reference

Use this page to better understand the fields displayed in this documentation.

Field Descriptions
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
Required
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.
Optional
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
Required
totalOrderItemPriceAfterDiscounts
The whole order item price after all applicable discounts are applied, including the Citrus discount.
Required
Groups Explained
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".

Integration - Previous

Magento V1.9 Plugin Installation and Configuration

Next - Integration Guides

Requesting Ads (the "Context" and its Parts)

Last updated 4 months ago

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	Required
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.	Optional
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	Required
totalOrderItemPriceAfterDiscounts	The whole order item price after all applicable discounts are applied, including the Citrus discount.	Required