Export integrations

This document describes the structure for our generic export integration mechanisms for sales, register close statements, product edit events, newsletter signups and future exportable entities.

The data types that can currently be exported are:

  • Checkouts
  • Sales
  • Register Close Statements
  • Products Edit Events
  • Newsletter Signups
  • Stock Events
  • Incoming Order State Change Events
  • Outgoing Orders

All exports happen through the same internal mechanism, namely the Export Queues.

Export Queues Overview

For each event that can be exported, the Ka-ching system can be configured to place the event entity in any number of queues. For instance, for each sale, the system can be configured to place the sale in two different export queues.

The export happens in three steps:

  1. Trigger
  2. Transformation
  3. Delivery

Trigger

Each queue can be configured to trigger an export to an external system in different ways:

  • Real time
  • By cron job

If the queue is configured to trigger real time, then an export will be started for each entity in the queue. If the cron job trigger is used, then the export will be performed in batches either daily or hourly based on the trigger configuration.

Transformation

When an export is performed, the data in the queue is first passed through a transformation step. Here you can configure an optional transformation of the exported data. Note that the expression forms in this step do have some limitations, so it should be considered to export the full data as it is and transform it at the receiving system.

Delivery

When the data is transformed it is passed to the delivery step. Here a configuration can specify to deliver to a web hook (an https endpoint), send an email, push to an FTP server and more.

Success / failure

When items in the queue are processed, they will end up in either a failure log or a success log. In case of failures, an error message from the delivery will be included, in order to make debugging integrations easier.

Trigger Types

Real time

The real time trigger takes a single element from the queue each time an element is added to the queue. The logical implication is that this trigger type will likely have a larger performance impact on the receiving end - since a request is made for each and every element.

Cron

This trigger can be configured to run once per hour or once per day and thus aggregates all the elements in the queue and process them in one go.

Built-in transforms

Identity

No transform is applied, and the JSON model will be our internal model as described in the Models documentation.

Mustache / handlebars

Mustache is a generic template language that can be used to output all sorts of data, like for instance JSON or HTML. Here is a link to the official Mustache template documentation https://mustache.github.io. The handlebars export is similar to mustache, but is a bit more flexible. The documentation can be found here: http://handlebarsjs.com.

CSV

The CSV export is quite elaborate and can be configured to provide a huge variety of content. Line items can be aggregated together and grouped by things like VAT. Payment transactions can be grouped together by type and currency.

Simple JSON

The Simple JSON transform lets you describe a simple, flat JSON output structure.

Built-in delivery methods

Email

Configure this in order to send the transformed data as an attachment to a number of email recipients.

Web hook

The web hook integration is a simple and easy way for you to obtain real time updates of sales from the Ka-ching system without the need to build your own integration framework. Each sale can be transformed or left as is and be POST’ed to a URL. This would most likely require some kind of credentials or token to be added as part of the URL or set as an auth header when the POST is performed.

Retry mechanism

We've built a retry mechanism that kicks in under certain circumstances to avoid manual handling of failed exports that have a chance to succeed if tried again a bit later. We will attempt an export up 5 times total (including the initial attempt) if:

  • The trigger is realtime and
  • The delivery is web hook and
  • The response code is 503, 522 or 524 or if the error is a timeout or connection refused

Exportable Content

All exported elements will be wrapped in a JSON dictionary. If you're using a cron export there will potentially be more than 1 element in the dictionary, but if you're using realtime export you're guaranteed to only have 1 element in the dictionary. 

{
    "<element-key>": {
        ...
    },
    "<element-key-2>": {
        ...
    }
}

Checkouts

You can configure an export integration that will receive all checkouts from an entire account in the Ka-ching system. The Checkout entity is described in details in the Models document.

Sales

You can configure an export integration that will receive all sales from an entire account in the Ka-ching system. The Sales entity is described in details in the Models document and includes information about the line items in the sale, the payment transactions used to pay for the sale, the applied discounts and taxes, information about the source of the sale and the time of the sale.

Register Close Statements

You can configure an export integration that will receive all register close statements from an entire account in the Ka-ching system. The Register close statements entity is described in details in the Models document and includes information about aggregated totals for sales, returns and grouped by product group. It also contains information about the reconciliations of payment types and information about the source of the register close statement and the time of the register close event.

Product Edit Events

You can configure the system to perform an export of product details every time they change in the system. This is useful for the situation where you use the Ka-ching system as the primary source for products and wish other systems to reflect any changes made to the products. Product creation, product changes and product deletion events are exported.

Newsletter Signup Events

It's possible to configure Ka-ching POS or SecondScreen apps to enable a very basic newsletter signup form asking for email address. This information can be sent to systems like Mailchimp using an export-configuration transforming the newsletter signup-event to the format required to sign up in Mailchimp.

Stock Events

It's possible to get all stock events in the system through exports. The exported element looks like this:

{
    "<element-key>": {
        "adjustment" : <number, optional, either adjusment or new_stock_value must be present>,
        "new_stock_value": <number, optional, either adjusment or new_stock_value must be present>,
        "product_id" : "<string, required>",
        "variant_id" : "<string, optional, present if it's a variant product>",
        "sale_id" : "<string, optional, present if stock change is due to a sale>",
        "stock_location_id" : "<string, required>",
        "stock_count_diff": <number, optional, present if event comes from a stock count>,
        "stock_count_expected": <number, optional, present if event comes from a stock count>,
        "stock_count_id": "<string, optional, present if event comes from a stock count>",
        "timestamp" : "<string, ISO 8601 format, required>",
        "type" : "<string, required, can be return, sale, received, stock_count_reset or external_reset>"
    }
}

The stock event export can be filtered to ignore certain types of events.

Incoming Order State Change Events

When an incoming order changes state in Ka-ching it's possible to receive notification of this event. The exported element looks like this:

{
    "order": <order, required>,
    "state": <order state, required>
}

Definition of the order object kan be found on our Models page.

Here's the definition of order state:

{
  "created" : <number, epoch timestamp in seconds>,
  "last_change" : <number, epoch timestamp in seconds>,
  "last_change_by" : <cashier, optional>,
  "last_change_comment" : "<string, optional>",
  "order_state" : "<string, required, can be either created, processing, ready, completed, rejected, cancelled>"
}

The cashier object is defined as follows:

{
  "display_name" : "<string, usually initials, required>",
  "full_name" : "<string, optional>",
  "identifier" : "<string, required>",
  "image_url" : "<string, https url to image of store associate, optional>"
}

Outgoing Orders

When an order is created in Ka-ching POS, and it is not being sent internally in the system to another shop, then it is exported as an 'outgoing order'.

Previously e-commerce orders were only indirectly sent through a sale entity, and the receiver would have to do some filtering to find the e-commerce line items. Now an order entity is created instead - and the intergrating system can send 'outgoing order state changes' back into Ka-ching in order to keep the system in sync with what happens to the order.

Definition of the order object kan be found on our Models page.