> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Import orders
> Import or update transaction orders and their line items in Kameleoon to power product recommendations and analytics.
This endpoint allows you to import a list of transaction orders into your Kameleoon account. You can also use this endpoint to update orders and their properties if they already exist in our database. The data should be sent as a [JSON string in the request’s body](#example-json-request).
## HTTP Request
```
POST https://api.products.kameleoon.com/sync/orders
```
## List of query parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop_id` | String | True | Your Store Key. You can find this in **Recommendations** > **Settings** > **Store settings** in the Kameleoon app. You can also contact your Customer Success Manager for the key. |
| `shop_secret` | String | True | Your Secret Key. You can find this in **Recommendations** > **Settings** > **Store settings** in the Kameleoon app. You can also contact your Customer Success Manager for the key. |
| `orders` | Array | True | List of orders. Find in [this table](#list-of-parameters-for-orders-object) the parameters required for `orders`. |
## List of parameters for `orders` object
| Parameter | Type | Required | Description |
| ------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | True | Order ID |
| `external_id` | String | True | This is a unique identifier associated with a user in your system or CRM. **(To ensure accurate matching with Kameleoon `VisitorCode`, the ID must first be stored as a Kameleoon Custom Data. When setting up this custom data, make sure to enable the option `Use this custom data as a unique identifier for cross-device matching` to ensure that the ID is used to link user activities across both systems.)** |
| `status` | String | True | Order status (for example, Processing, Out for delivery, Delivered) |
| `channel` | String | True | Medium used for order (for example, Website, App, In-store) |
| `date` | Integer | True | Unix timestamp in seconds of when the order was placed or updated |
| `offline` | Boolean | False | Flags orders as offline. It is set to `false` by default |
| `location_id` | String | True | User's location (city) ID |
| `promocode` | String | False | Promo code used in the order |
| `delivery_type` | String | False | Delivery type (for example, Courier, Pickup in-store) |
| `delivery_address` | String | False | Destination address for CRM |
| `delivery_date` | Date | False | Expected delivery date. Format: "YYYY-MM-DD" |
| `delivery_time` | Time | False | Expected delivery time. Format: "HH:MM" |
| `payment_type` | String | False | Payment type (for example, Cash, Card, Wire) |
| `tax_free` | Boolean | False | Indicates whether the item is tax-free |
| `bank_issuer` | String | False | Bank issuer |
| `bank_pos_processor` | String | False | Indicates what point of sales (POS) system/terminal was used at the time of payment |
| `bank_loyalty_program` | String | False | Bank loyalty program |
| `bank_total_installment` | Integer | False | Total installments needed to be paid through the bank |
| `payment_card_provider` | String | False | Payment card provider |
| `gift_package` | Boolean | False | Indicates whether the item will be in a gift package |
| `value` | Object | True | Order grand total. Find the required parameter for `value` in [this table](#list-of-parameters-for-value-object). |
| `payment_structure` | Object | True | A breakdown of the payment (for example, cash payments, discounts, delivery fees). Find the parameters required for `payment_structure` in [this table](#list-of-parameters-for-payment_structure-object). |
| `items` | Object | True | Everything that is included in the order. Find the parameters required for `items` in [this table](#list-of-parameters-for-items-object). |
## List of parameters for `value` object
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `Total` | Numeric | True | Order total |
## List of parameters for `payment_structure` object
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | --------------------------------------------------------------- |
| `cash` | Numeric | False | Indicates what portion of the order total was paid in cash |
| `bonuses` | Numeric | False | Indicates what portion of the order total was paid with bonuses |
| `delivery` | Numeric | False | Indicates the cost of the order's delivery |
| `discount` | Numeric | False | Indicates the order's discounted value |
Please ensure that `value.total == payment_structure.cash + payment_structure.bonuses + payment_structure.delivery - payment_structure.discount`
## List of parameters for `items` object
| Parameter | Type | Required | Description |
| ------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `id` | String | True | Purchased product's ID |
| `price` | Numeric | True | Price of a single unit of the product |
| `quantity` | Integer | True | Total quantity of the chosen product(s) |
| `status` | String | True | Item status; can only be: `created`, `invoiced`, `shipped`, `delivered`, `cancelled`, `refunded` |
| `original_price` | Numeric | False | Product's original price |
| `discount_product` | Numeric | False | Product's discounted price |
| `discount_bonuses` | Numeric | False | Product's discounted bonuses |
| `delivery_company` | String | False | Postal service that delivered the item |
| `barcode` | String | False | Product's barcode |
| `line_id` | String | False | Unique ID for this product's position (line item) in your store's order system. |
| `cancel_reason` | String | False | Cancellation reason |
The `items` object is required when you create an order. You can send it as an empty array when updating an order's status.
## Example JSON request
```json theme={null}
{
"shop_id": "DvLWN2ZTMZ",
"shop_secret": "EIxTuot8sj",
"orders": [
{
"id": "yKsvZbWpCL",
"external_id":"jhfakfkadak",
"status": "Processing",
"channel": "In-store",
"date": 1602338740,
"offline": false,
"location_id": "7701123",
"promocode": "vxawxSi9Uy",
"delivery_type": "courier",
"delivery_address": "111 Peter Street, Toronto, ON, M5V 2H1",
"delivery_date": "2021-12-21",
"delivery_time": "15:00",
"tax_free": false,
"bank_issuer": "Scotiabank",
"bank_pos_processor": "Clover",
"bank_loyalty_program": "PC Optimum",
"bank_total_installment": 0,
"payment_card_provider": "Visa"
"gift_package":true,
"value": {
"total": 200.13,
},
"payment_structure": {
"cash": 190,
"bonuses": 15,
"delivery": 20,
"discount": 24.87
},
"items": [
{
"id": "ITEM-ID-1",
"price": 205,
"quantity": 1,
"status": "created",
"original_price": 230,
"discount_product": 30,
"discount_bonuses": 20,
"delivery_company": "Canada Post",
"barcode_id": "195204003541",
"line_id": "195204003541-22323443-123434",
"cancel_reason": "none",
},
}
...
]
},
...
]
}
```
## Canceling an order
Since the Import orders endpoint is used for both creating and updating orders, you can use it to register a canceled order.
To register a canceled order, provide the following:
### Query parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop_id` | String | True | Your Store Key. You can find this in **Recommendations** > **Settings** > **Store settings** in the Kameleoon app. You can also contact your Customer Success Manager for the key. |
| `shop_secret` | String | True | Your Secret Key. You can find this in **Recommendations** > **Settings** > **Store settings** in the Kameleoon app. You can also contact your Customer Success Manager for the key. |
| `orders` | Array | True | List of orders. Provide the orders you'd like to register as canceled. |
### `orders` object parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------- |
| `id` | String | True | Order ID |
| `status` | String | True | Order's status (set to `cancelled`) |
### Example cancellation JSON request
```json theme={null}
{
"shop_id": "DvLWN2ZTMZ",
"shop_secret": "EIxTuot8sj",
"orders": [
{
"id": "yKsvZbWpCL",
"status": "Cancelled"
},
...
]
}
```