Syncing Order Data Via API

Sending Order Data to CitrusAd

To send order data to CitrusAd, use a command similar to the command below. Note that the data in the "orders" field below is dummy data and is provided here only as an example.

The examples below all display use of Order Attribution Option 1. For more information on attributing orders and attribution options, please see Syncing Order Data:

Minimum Viable Order Context

Below is the minimum required context to sync orders. View the reference at the bottom of the page to see all supported fields.

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string"
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string"
}
]
}
]
}'

If you are sending all order data to CitrusAd, the adId field is only required for orders requiring attribution to ads.

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}
cURL
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}

A mock version can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "",
"sessionId": null,
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
cURL
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "",
"sessionId": null,
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}

Detailed Order Context

A detailed context can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"id": "string",
"teamId": "string",
"customerId": "string",
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
"citrusDiscountAmount": "number",
"substitutedFor": "orderItemObject"
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"id": "string",
"teamId": "string",
"customerId": "string",
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
"citrusDiscountAmount": "number",
"substitutedFor": "orderItemObject"
}
]
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}
cURL
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}

A mock version can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"id": "1985988a-6f9f",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "6.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"citrusDiscountAmount": "3.00"
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"id": "1985988a-6f9f",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "6.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"citrusDiscountAmount": "3.00"
}
]
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"sessionId": null,
"id": "1985988a-6f9f",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": 3.00,
"gtin": "9891998566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 6.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
cURL
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"sessionId": null,
"id": "1985988a-6f9f",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": 3.00,
"gtin": "9891998566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 6.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}

Syncing Multiple Orders

If you are syncing multiple orders, you can send up to 100 items per request as a batch. The number of requests that you can make is not limited.

The order of the payload pushed is the same order as the result returned. This makes it possible for the data to be congruent with the order representation that the integrator maintains in their backend.

A detailed context can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"id": "string",
"teamId": "string",
"customerId": "string",
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
"citrusDiscountAmount": "number",
"substitutedFor": "orderItemObject"
}
]
},
{
"id": "string",
"teamId": "string",
"customerId": "string",
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
"citrusDiscountAmount": "number",
"substitutedFor": "orderItemObject"
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"id": "string",
"teamId": "string",
"customerId": "string",
"orderDate": "string (iso date)",
"orderItems": [
{
"gtin": "string",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
"citrusDiscountAmount": "number",
"substitutedFor": "orderItemObject"
}
]
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
},
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}
cURL
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}

A mock version can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"id": "1985988a-6f9f",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "6.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"citrusDiscountAmount": "3.00"
}
]
},
{
"id": "1985988a-7a3s",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "t4345104-1c4a-9a0d",
"orderDate": "2019-12-02T15:01:00Z",
"orderItems": [
{
"gtin": "9079153R",
"quantity": 1,
"regularUnitPrice": "19.99",
"totalOrderItemPriceAfterDiscounts": "19.99",
"adId": "display_wexcre3jV8VRxB1w_iEPy_uLxFPc5ODkxBRA2UAW3",
"citrusDiscountAmount": "0.00"
}
]
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/orders?" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"orders": [
{
"id": "1985988a-6f9f",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"orderDate": "2019-12-02T15:00:00Z",
"orderItems": [
{
"gtin": "9891566P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "6.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"citrusDiscountAmount": "3.00"
}
]
},
{
"id": "1985988a-7a3s",
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "t4345104-1c4a-9a0d",
"orderDate": "2019-12-02T15:01:00Z",
"orderItems": [
{
"gtin": "9079153R",
"quantity": 1,
"regularUnitPrice": "19.99",
"totalOrderItemPriceAfterDiscounts": "19.99",
"adId": "display_wexcre3jV8VRxB1w_iEPy_uLxFPc5ODkxBRA2UAW3",
"citrusDiscountAmount": "0.00"
}
]
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"sessionId": null,
"id": "1985988a-6f9f",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": 3.00,
"gtin": "9891566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 6.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "t4345104-1c4a-9a0d",
"sessionId": null,
"id": "1985988a-7a3s",
"orderItems": [
{
"regularUnitPrice": 19.99,
"citrusDiscountAmount": 0.00,
"gtin": "9079153R",
"adId": "display_wexcre3jV8VRxB1w_iEPy_uLxFPc5ODkxBRA2UAW3",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 19.99
}
],
"orderDate": "2019-12-02T15:01:00Z"
}
]
}
cURL
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "b1445104-1c4a-4c4c",
"sessionId": null,
"id": "1985988a-6f9f",
"orderItems": [
{
"regularUnitPrice": 9.99,
"citrusDiscountAmount": 3.00,
"gtin": "9891566P",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 6.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "t4345104-1c4a-9a0d",
"sessionId": null,
"id": "1985988a-7a3s",
"orderItems": [
{
"regularUnitPrice": 19.99,
"citrusDiscountAmount": 0.00,
"gtin": "9079153R",
"adId": "display_wexcre3jV8VRxB1w_iEPy_uLxFPc5ODkxBRA2UAW3",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 19.99
}
],
"orderDate": "2019-12-02T15:01:00Z"
}
]
}

Reference

Relevant Context Fields

String

Description

Required?

adId

The ad ID. This field should be populated if this order item has been bought as a result of a view or click on an ad.

Optional

adIds

The sd 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

citrusDiscountAmount

The amount of the CitrusAd discount that was applied to the ad. The application to an ad of both a discount amount and additional constraints can cause the CitrusAd discount value to be less than the maximum value of the original ad.

Required for Discounts

customerId

The id of the customer that has created the order.

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

id

This is the Id of the oder you are pushing to CitrusAd. Can be populated with the order Id maintained in the integrator's system. If no value is provided, one will be generated in the returned object.

Optional

orderDate

The date of the order. Required in ISO format.

Required

orderItems

The items included in the order being pushed to CitrusAd.

Required

quantity

The number of the gtin purchased

Required

regularUnitPrice

The regular price of the item added to cart

Required

sessionId

This is a generated id that you control that identifies a user's session. CitrusAd can use this for purchase attribution.

Optional

teamId

Your retailer teamId, this is used to identify the orders are coming from your team. Can be deduced from the API key.

Optional

totalOrderItemPriceAfterDiscounts

The whole order item price after all applicable discounts are applied, including the CitrusAd discount.

Required

your_api_key_here

Your API key

Required

For a glossary of all terms in the documentation, see the reference.