Orders

Orders are also sometimes called sales or invoices.

Get orders

Use this endpoint to retrieve sales history.

GET /v1/companies/5678/orders ?created_gte=2013-06-01 Get all orders created on or after a given date*
GET /v1/companies/5678/orders ?value_lt=100 Get all orders worth less than $100*
GET /v1/companies/5678/orders/complete Get all complete orders**
GET /v1/companies/5678/orders/pending/accounts Get all pending account sales
GET /v1/companies/5678/orders/discounted Get all discounted orders
GET /v1/companies/5678/orders/deleted Get all orders deleted from the POS
GET /v1/companies/5678/orders/linkedcustomer Get all orders where a customer is attached
GET /v1/companies/5678/customers/4289/orders Get all orders for a given customer
GET /v1/companies/5678/sites/823/orders Get all orders for a given site
GET /v1/companies/5678/registers/16/orders Get all orders for a given register
GET /v1/companies/5678/staff/732846/orders Get all orders created by a given staff member
GET /v1/companies/5678/sites/823/registers/16/staff/732846/customers/4289/orders/complete/discounted ?created_gte=2013-06-01&value_lt=100 Combination of above filters
  • All the variations of the orders endpoint above act as filters, which can be combined indiscriminately. For example, /v1/companies/5678/orders/sites/823/staff/732846 will filter by site and staff member.
  • * For limiting by creation date and value, you can use specific values, e.g. /v1/companies/5678/orders ?created=2013-06-01, or combine suffixes lt, lte, gt and gte to specify ranges, e.g. /v1/companies/5678/orders ?value_gte=50&value_lt=100 for 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

GET /v1/companies/5678/orders/93824701 Get an order by ID
GET /v1/companies/5678/orders/saleid/tj4ds8n3 Get an order by Sale ID
  • saleid is the 8 character ID printed on receipt.
  • The price_variation field 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_variation value of 0.95 on that line.
  • line_total_ex_tax in 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 (callback_uri, lock etc).
  • The options attribute contains any option sets in this order. See the Update an order

Create an order

POST /v1/companies/5678/orders Submit a new order
  • Orders cannot be created with status ACCEPTED. If status is omitted, SUBMITTED will be assumed. See the Update an order action for a list of valid order statuses.
  • If you include a callback_uri, Kounta will POST the order to it whenever the order's status changes. To test the callback, change an order’s status (see Update an order).
  • Orders are posted to callback_uri as 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 above, product 3091 will 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_price should be specified as an ex tax price.
  • Use the price_variation fields for discounts and surcharges. The values work as a coefficients of the line/order’s subtotal. For example, 0.9 means a 10% discount, and 1.15 means a 15% surcharge.
  • Include a price_limit to 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_id instead of a site_id.
  • By default, and order’s status is changed to COMPLETE when it’s paid. Set complete_when_paid to false if you want to use the COMPLETE status as a delivery notification. The POS operator will manually mark the order as completed when it’s delivered.
  • Orders created in a SUBMITTED status 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 enable_alert_sound to false.

Use 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 payments.
  • DELETE - They won’t be able to delete your order.
  • ALL - All of the above. They won't be able to edit your order.

All fields are optional, but you must include either register_id or site_id. You can, as an alternative, create a blank order and add lines and payments in subsequent requests:

POST /v1/companies/5678/orders Create a blank order

If options are provided the order will be created with the provided option sets. Option sets can be nested by using the same options schema inside each of the option_sets items.

POST /v1/companies/5678/orders Submit a new order with option sets

Update an order

PUT /v1/companies/5678/orders/93824701 Update an order
  • Orders with COMPLETE status cannot be updated.

The 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 PENDING to COMPLETE if it is paid and the complete_when_paid flag is true.

You can add, update, remove, and re-order lines and payments using the Lines and Payments endpoints.

Refund an order

PUT /v1/companies/5678/orders/93824701 Refund an order
  • Order must have status COMPLETED if original_order_id is provided.

Option sets

An order may contain option sets. These are available through the options attribute:

GET /v1/companies/5678/orders/93824701 Get an order by ID

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 attribute part_of_option_set with a value of true.

If the option set supports instructions an option may include an instructions attribute with one of the four fixed values: No, Extra, Only or On Side.

Get an option set

GET /v1/companies/5678/orders/93824701/optionsets/1 Get an option set for an order
  • 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

POST /v1/companies/5678/orders/93824701/optionsets Get an option set

Delete an option set

DELETE /v1/companies/5678/orders/93824701/optionsets/1 Delete an option set

Webhooks

Here is a list of the supported webhook topics.

orders/completed

When an order is marked as complete. You will receive the complete order.

You also may provide the following attribute filters:

  • customer

orders/customer

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.

orders/deleted

When an order is deleted. You will receive the complete order.

orders/kitchen

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.