# Syncing Order Data Via API
## Sending Order Data to Project Agora Commerce
To send order data to Project Agora Commerce, 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.
### 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.
{% tabs %}
{% tab title="HTTP" %}
```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=pa_id",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string"
}
]
}
]
}
```
{% endtab %}
{% tab title="cURL" %}
```bash
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=pa_id",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string"
}
]
}
]
}'
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
If you are sending all order data to Project Agora Commerce, the `adId` field is only required for orders requiring attribution to ads.
{% endhint %}
If successful, you will get the following object returned:
{% tabs %}
{% tab title="HTTP" %}
```http
HTTP/2 200
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string=pa_id",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}
```
{% endtab %}
{% tab title="cURL" %}
```bash
{
"orders": [
{
"adIds": "string",
"teamId": "string",
"customerId": "string",
"sessionId": "string",
"id": "string",
"orderItems": [
{
"regularUnitPrice": number,
"citrusDiscountAmount": number,
"gtin": "string=pa_id",
"adId": "string",
"quantity": integer,
"substitutedFor": "string",
"totalOrderItemPriceAfterDiscounts": number
}
],
"orderDate": "string"
}
]
}
```
{% endtab %}
{% endtabs %}
#### A mock version can be seen below:
{% tabs %}
{% tab title="HTTP" %}
```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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
}
]
}
```
{% endtab %}
{% tab title="cURL" %}
```bash
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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
}
]
}'
```
{% endtab %}
{% endtabs %}
If successful, you will get the following object returned:
{% tabs %}
{% tab title="HTTP" %}
```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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
```
{% endtab %}
{% tab title="cURL" %}
```bash
{
"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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
```
{% endtab %}
{% endtabs %}
### Multiple items per order
In case you are sending multiple items in one order (this is the common case) , you will need to separate each object by the "," character as seen in the following example.
In this example we are sending two different SPL items in the same order:
{% tabs %}
{% tab title="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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
},
{
"gtin": "catpref--456789",
"quantity": 6,
"regularUnitPrice": "7.99",
"totalOrderItemPriceAfterDiscounts": "7.99",
"adId": "display_uipll5hN7VRyA1wp_yOpL_hadIOj5OTkfUTR2UC=="
}
]
}
]
}
```
{% endtab %}
{% tab title="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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
},
{
"gtin": "catpref--456789",
"quantity": 6,
"regularUnitPrice": "7.99",
"totalOrderItemPriceAfterDiscounts": "7.99",
"adId": "display_uipll5hN7VRyA1wp_yOpL_hadIOj5OTkfUTR2UC=="
}
]
}
]
}'
```
{% endtab %}
{% endtabs %}
If successful, you will get the following object returned:
{% tabs %}
{% tab title="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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
},
{
"regularUnitPrice": 7.99,
"citrusDiscountAmount": null,
"gtin": "catpref--456789",
"adId": "display_uipll5hN7VRyA1wp_yOpL_hadIOj5OTkfUTR2UC==",
"quantity": 6,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts":7.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
```
{% endtab %}
{% tab title="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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_uLxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
},
{
"regularUnitPrice": 7.99,
"citrusDiscountAmount": null,
"gtin": "catpref--456789",
"adId": "display_uipll5hN7VRyA1wp_yOpL_hadIOj5OTkfUTR2UC==",
"quantity": 6,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts":7.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}
```
{% endtab %}
{% endtabs %}
### Multiple orders
In case you want to send multiple different orders you will have to separate them like different objects inside the "order" object.
In this example we are sending two different orders (made at a different time as shown in the orderDate field) one for an SPL item and one for a Static Banner:
{% tabs %}
{% tab title="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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
},
{
"orderDate": "2019-12-02T15:07:05Z",
"orderItems": [
{
"gtin": "catpref--657942",
"quantity": 4,
"regularUnitPrice": "5.99",
"totalOrderItemPriceAfterDiscounts": "5.99",
"adId": "banner_ihjoP6jt7RTxB6q_yTUy_poaFALL9jghMNU1yL=="
}
]
}
]
}
```
{% endtab %}
{% tab title="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": "catpref--123456",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="
}
]
},
{
"orderDate": "2019-12-02T15:07:05Z",
"orderItems": [
{
"gtin": "catpref--657942",
"quantity": 4,
"regularUnitPrice": "5.99",
"totalOrderItemPriceAfterDiscounts": "5.99",
"adId": "banner_ihjoP6jt7RTxB6q_yTUy_poaFALL9jghMNU1yL=="
}
]
}
]
}'
```
{% endtab %}
{% endtabs %}
If successful, you will get the following object returned:
{% tabs %}
{% tab title="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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "",
"sessionId": null,
"id": "5o40r628-y580-5k69-7t66-b88bbwtups80",
"orderItems": [
{
"regularUnitPrice": 5.99,
"citrusDiscountAmount": null,
"gtin": "catpref--657942",
"adId": "banner_ihjoP6jt7RTxB6q_yTUy_poaFALL9jghMNU1yL==",
"quantity": 4,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 5.99
}
],
"orderDate": "2019-12-02T15:07:05Z"
}
]
}
```
{% endtab %}
{% tab title="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": "catpref--123456",
"adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA==",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 9.99
}
],
"orderDate": "2019-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "",
"sessionId": null,
"id": "5o40r628-y580-5k69-7t66-b88bbwtups80",
"orderItems": [
{
"regularUnitPrice": 5.99,
"citrusDiscountAmount": null,
"gtin": "catpref--657942",
"adId": "banner_ihjoP6jt7RTxB6q_yTUy_poaFALL9jghMNU1yL==",
"quantity": 4,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 5.99
}
],
"orderDate": "2019-12-02T15:07:05Z"
}
]
}
```
{% endtab %}
{% endtabs %}
### Banner Order Syncing
If more than one products that show up in the landing page of a banner ,are added to cart and all of them are related with the banner campaign (you can see which products are related with a specific banner campaign in the response you get from us, and specifically in the gtins table), you have to choose one of them in random and send the order only once with the banner ad id and the respective pa\_id(gtin) like in the example above.
For example if you get this banner response:
```
{
"ads": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Category_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Category banner for brandx laptop",
"text": "",
"gtins": [
"catpref--2899049P",
"catpref--9891566P",
"catpref--2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z",
"tags": {}
}
],
"products": []
}
```
and the user has made an order for the products with pa\_ids: catpref--2899049P and catpref--2902620P, then you will have to chose in random only one of them to send like below:
```
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": "catpref--2899049P",
"quantity": 3,
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
"adId": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA=="
}
]
}
]
}
```
While sending the order data for SPL or DSPL ads, it is important to remember that you will have to keep the values of ad id and pa\_id for each sponsored product after getting the respective response from our system. An order shall be attributed to an SPL or DSPL item, either when the product has been added to cart from the "add to cart" button from a category page, either while added from the product details page when the user has been landed there after a click to the respective SPL or DSPL item.
The same applies for Banner ads. An order shall be attributed to a Banner item, when any product that exists in the landing page of the Banner ad and its pa\_id is included in the Banner ad response, is added to the cart. So you will have to keep the ad id and pa\_id values also in this case in order to use them when syncing the order.
### 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 |
| citrusDiscountAmount | The amount of the Project Agora Commerce discount that was applied to the ad. The application to an ad of both a discount amount and additional constraints can cause the Project Agora Commerce discount value to be less than the maximum value of the original ad. | Required for Discounts |
| gtin | This is the pa\_id as used in the xml product feed (catprefix--"SKU").
| Required |
| id | This is the Id of the order you are pushing to Project Agora Commerce. 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 Project Agora Commerce. | Required |
| quantity | The number of the gtin purchased | Required |
| regularUnitPrice | The regular price of the item added to cart | Required |
| 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 Project Agora Commerce discount. | Required |
| your\_api\_key\_here | Your API key | Required |
For a glossary of all terms in the documentation, see the reference
{% hint style="info" %}
The "adId" and "gtins" fields in the "orderItems" object should be filled with the "id" and "pa-id" fields taken from the responses of an SPL, DSPL or Banner request.
It is important to save the values of "id" and "pa-id" in each step so as to use them in a later stage when sending the order object with the API
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developers-commerce.projectagora.com/integration/syncing-order-data/syncing-order-data-via-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.