Reference

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
placement	This is a required variable for all kind of requests. It defines the type of the request	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 Project Agora Commerce. 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 Project Agora Commerce 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 Project Agora Commerce	Required
orders	The type of object being pushed to Project Agora Commerce. 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 Project Agora Commerce when catalog product information was sent to Project Agora Commerce. 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. Project Agora Commerce 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 Project Agora Commerce discount.	Required
position	The ad's position in the Project Agora's response.	Optional

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".