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