Incoming Orders
The Incoming Orders Import Endpoint
https://{BASE_URL}/imports/incoming_orders?...&stock_location={STOCK_LOCATION}
All import integration endpoints use the same authentication parameters, please see Authentication page for more details.
In addition to this the incoming orders endpoint also requires you to specify a stock location when creating an incoming order.
Since the nature of incoming orders are event-like, they cannot be undone by deleting them.
It is currently not possible to update an incoming order after creation.
Queueing one or more incoming orders for import requires you to send a HTTP POST request with the above parameters. The Content-Type should be application/json.
The body of the request must contain one or more incoming orders. You can queue as many incoming orders as you would like (at least one).
Upon success a HTTP 200 OK reponse will be given with body looking something like this:
{
"status": "OK",
"message": "Import of 1 order(s) initiated"
}
In general the endpoint reponse will let you know if any of the incoming orders posted was not queued for import. It will also (if possible) let you know which of the actually failed.
Minimum incoming order import body
A minimum incoming order must have an order_identifier that must be unique across all incoming orders on the given stock location and a basket. A minimum basket must have a currency and a non-empty array of line_items.
{
"orders": [
{
"order_identifier": "AKGJTHE",
"basket": {
"currency": "DKK",
"line_items": [
{
"product_identifier": "KGJFITK",
"name": "Shiny product",
"quantity": 1,
"price": 10
}
]
}
}
]
}
Full incoming order import body
{
"orders": [
{
"order_identifier": "AKGJTHE",
"customer": {
"customer_identifier": "FKSOEKD",
"name": "Jane Doe"
},
"basket": {
"currency": "DKK",
"discounts": [
{
"type": "percentage",
"amount": 0.05,
"name": "5% off entire purchase"
}
],
"line_items": [
{
"product_identifier": "KGJFITK",
"name": "One product",
"quantity": 1,
"price": 10
},
{
"product_identifier": "GJKRIGJ",
"name": "Other product",
"quantity": 10,
"price": 50,
"discounts": [
{
"type": "amount_per_item",
"amount": 5,
"name": "5 DKK off every item"
}
]
}
]
},
"payment": {
"reference": "ASD-123"
}
}
]
}
Models
Order
order_identifier must be a string that is unique across all incoming orders for the given stock location.
basket must be a basket, see Basket for more information.
customer is an optional Customer, see Customer for more information
{
"order_identifier": "FHGJRIL",
"basket": {},
"customer": {},
"payment": (optional),
"shipping": (optional)
}
Basket
currency must be the ISO4217 currency representation for the basket. See Wikipedia article on the subject for more information.
line_items must be a non-empty array of line items.
discounts is an optional array of discounts applied to the entire basket. See Discount for more information.
{
"currency": "DKK",
"line_items": [],
"discounts": []
}
Customer
customer_identifier is an optional string.
name is an optional string. This is user facing.
phone_number is an optional string. This is user facing.
email is an optional string. This is user facing.
{
"customer_identifier": "NGJFITK",
"name": "Lisa Kaching",
"phone_number": "+45 12 34 56 78",
"email": "lisa@ka-ching.dk"
}
LineItem
product_identifier must be a string.
variant_identifier is an optional string.
barcode is an optional string.
image_url is an optional URL string pointing to a png or a jpg image. Please make sure that the server adheres to the Apple App Transport Security specification
name must be a string. This is user facing.
quantity must be a positive integer.
price must be a positive float.
discounts is an optional array of discounts applied to this line item. See Discount for more information.
{
"product_identifier": "GJFIKEL",
"variant_identifier": "DKFJIAL",
"barcode": "9876483763526",
"image_url": "https://some.url/image",
"name": "Your new shiny product",
"quantity": 2,
"price": 10,
"discounts": []
}
Discount
A discount can be applied to a line item and/or a basket.
name must be a string and is shown to the user.
type must be one of the possible DiscountType values mentioned below.
amount must be a number, if type is percentage it must be between 0 and 1 for the corresponding percentage.
Example of a discount:
{
"name": "20% discount",
"type": "percentage",
"amount": 0.2
}
DiscountType
Can be one of the following:
amount- amount off on all items of a line item or a basketamount_per_item- amount off per item of a line item, not usable on a basketpercentage- percentage discount on line item or a basketnew_price- new price for all items of a line item, or a basketnew_price_per_item- new price per item of a line item, not usable on a basket
Payment
It's optional to specify a payment. If there's a payment object specified the order is assumed paid on arrival to Ka-ching, which means that Ka-ching will handle it as a Click & Collect order, where the customer just picks it up at the store. If no payment is specified Ka-ching will handle the order as a Reserve & Collect order where the customer will pay for the items at during pick up in the store.
{
"reference": "<string, required>"
}
Shipping
In case the order is paid, it can also optionally have shipping information included. This will tell the receiving store that they should ship the order to the address present in the shipping information.
In other words: If payment and shipping information is present, then the order is handled as a 'Ship from Store' order.
{
"address": {
"street": "<string, optional>",
"city": "<string, optional>",
"postal_code": "<string, optional>"
},
"method_id": "<string, optional>",
"method_title": "<L10nString, optional>",
"method_subtitle": "<L10nString, optional>",
}
The address information is presented to the cashier handling the order. The method specifies an optional alternative delivery method. The contents may custom defined and could for instance be:
"method_id": "express",
"method_title": "1 day Express Delivery",
"method_subtitle": "Free of charge"
or
"method_id": "package_box_02315",
"method_title": "Package box",
"method_subtitle": "Kiosk Stoppestedet, Stationsvej 2, 8732 Hovedgård"
This information is also presented to the order handler.