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.

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 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.
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.
items	Object	True	Everything that is included in the order. Find the parameters required for items in this table.

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

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

{
  "shop_id": "DvLWN2ZTMZ",
  "shop_secret": "EIxTuot8sj",
  "orders": [
    {
      "id": "yKsvZbWpCL",
      "status": "Cancelled"
    },
    ...
  ]
}