Orders are also sometimes called sales or invoices.
The Orders endpoint will return orders in all statuses by default. This includes both in-progress orders on the POS (i.e. statuses SUBMITTED, ON_HOLD, PENDING, ACCEPTED, REJECTED), as well as completed sales (where status is COMPLETE).
If you are only interested in completed sales, then ensure you set the correct filter in the
Use this endpoint to retrieve orders and sales history.
- All the variations of the
ordersendpoint above act as filters, which can be combined indiscriminately. For example,
/v1/companies/5678/orders/sites/823/staff/732846will filter by site and staff member.
- * For limiting by creation date and value, you can use
value_with suffixes of
lte(less than or equal to),
gt(greater than) and
gte(greater than or equal to), e.g.
/v1/companies/5678/orders/complete ?created_gte=2019-03-01, or combine multiple filters to specify ranges, e.g.
/v1/companies/5678/orders ?value_gte=50&value_lt=100for values $50–$99.99 (or whatever currency is in use by the site).
- ** Filter by order status by including the order status in lower case. See the Update an order action for a complete list of order status codes
Get an order
saleidis the 8 character ID printed on receipt.
price_variationfield may or may not be present on some lines, and on the order itself. There is no precedence between order- and line-level price variation; they simply multiply their respective subtotals. For example, to apply a 5% discount on a line, you would specify a
price_variationvalue of 0.95 on that line.
line_total_ex_taxin the order line is the final line price including all price variations from both line level and order level.
- Because completed orders are immutable, they are returned without some of the
transient information included in incomplete orders (
optionsattribute contains any option sets in this order. See the Update an order
order_typeattribute will not be visible if its value is empty or not specified
Create an order
- Orders cannot be created with
SUBMITTEDwill be assumed. See the Update an order action for a list of valid order statuses.
- If you include a
callback_uri, Kounta will
POSTthe order to it whenever the order's
statuschanges. To test the callback, change an order’s status (see Update an order).
- Orders are posted to
callback_urias JSON, unless the uri's query string includes
contentType=application/xml, in which case it will be posted as XML.
- Add line modifiers as an array of product IDs. You can
include the same ID more than once. To negate a modifier (e.g.
No Sugar), change the sign of the ID to negative. In the example
3091will be marked as a negator.
- When you omit a line’s
unit_price, the order’s site’s price for the line’s product will be used instead.
unit_priceshould be specified as an ex tax price.
- Use the
price_variationfields for discounts and surcharges. The values work as a coefficients of the line/order’s subtotal. For example,
0.9means a 10% discount, and
1.15means a 15% surcharge.
- Include a
price_limitto prevent POS operators from modifying an order beyond a given payable amount. Price limits can be useful if you've taken a pre-payment or pre-authorization on a company's behalf.
- If you want to send an order to a specific register, include a
register_idinstead of a
- By default, and order’s status is changed to
COMPLETEwhen it’s paid. Set
falseif you want to use the
COMPLETEstatus as a delivery notification. The POS operator will manually mark the order as completed when it’s delivered.
Orders created in a
SUBMITTEDstatus will trigger an alert sound on the POS to notify the merchant of a new order.
If you want to disable this sound from playing you can set
order_typecan be specified as one of
lock to prevent the POS operators from modifying parts of the order
you’ve created. Possible flags include:
NEW_LINES- They won't be able to add their own lines.
PAYMENTS- They won’t be able to add any payments.
APP_PAYMENTS- They will only be able to add your add-on's payment.
DELETE- They won’t be able to delete your order.
ALL- All of the above. They won't be able to edit your order.
options are provided the order will be created with
the provided option sets. Option sets can be nested by using the
options schema inside each of the
Update an order
- Orders with
COMPLETEstatus cannot be updated.
status field should be one of:
SUBMITTED- The order has been submitted and is awaiting approval from the company.
ON_HOLD- The order has been held for future processing (i.e. it is a pre-order).
ACCEPTED- The order has been accepted by the company, and is ready to be fulfilled.
REJECTED- The order has been rejected by the company (e.g. the order was cancelled or refunded).
PENDING- The order has been fulfilled and is awaiting payment.
COMPLETE- The order has been fulfilled and paid.
Kounta will automatically change an order’s status from
COMPLETE if it is paid and the
complete_when_paid flag is
Refund an order
- Order must have status
An order may contain
These are available through the
Since a single option set can span multiple lines on an order the option sets will be presented in their original form attached to the order (rather than the individual lines).
The order in the example above contains one option set that is
represented in the order lines 2 and 3. Each nested option set
selection will contain a
line_number that points to an
order line (the
number attribute on a line).
Lines (and their modifiers) that belong to an option set cannot be
modified directly. You must update the original option set instead.
The order lines that are part of an option set will contain the
part_of_option_set with a value of
If the option set supports instructions an option may include an
instructions attribute with one of the four fixed
Get an option set
- The option set number starts at 1 which represents the first option set on that order.
- See option sets for a full explanation.
Add an option set
- See option sets for a full explanation.
Delete an option set
Here is a list of the supported webhook topics.
When an order is marked as complete. You will receive the complete order.
You also may provide the following attribute filters:
When a customer, on whom a
reference_id has been set, is linked to or unlinked from an order,
you will receive the complete order.
When an order is deleted. You will receive the complete order.
When an action is taken on an order that would trigger kitchen print rules (e.g. put an order ON_HOLD). This is typically used for bump screen integrations. You will receive the complete order.