Vocabulary

In order to understand the overall documentation, it is necessary with a clear definition of the terms that we are using.

This section aims to describe the entirety of the terms that we use in the system. Any oversights should be reported to morten@ka-ching.dk

Account

When we talk about an account in Ka-ching, we are referring to your account in the Ka-ching system. An account may span several markets/countries and may contain many shops in each of these markets. Often an account will reflect an entire chain of shops.

User

An account is not directly coupled to a single user. Instead a user in the Ka-ching system simply refers to a validated identity - in other words an actual person. This de-coupling means that one user could for instance be an account owner (see definition for Account Owner) for several accounts - or shop owner (see definition for Shop Owner) for several shops - even shops spanning different accounts.

The de-coupling will have the advantage that the identity and credentials of a single user can be kept as a secret for that user, and not shared between many users. When for instance a shop owner leaves the company, the user access rights can just be withdrawn.

Market

A market in the Ka-ching system is a region in which the same currency is used and the same default taxes are used. In many situations a market will correspond to a country, but in some situations it may be beneficial to have several markets within the same country or alternatively one market spanning several countries.

Since all shops in the same market share their currency, the market is also the largest entity in which we aggregate sales statistics and the like.

Shop

A shop in the Ka-ching system corresponds to a physical shop. As such, a shop belongs to a specific market (read: country), and from here the shop gets the currency and default taxes.

Register

When we speak about a register we mean a physicial cash register - represented by the Ka-ching POS app running on an iPad or an iPhone. Typically one register will have a cash drawer, a printer, a scanner and a credit card terminal.

Cashier

A cashier represents the person that completes the sale at a cash register. Note that cashiers do not log into the system. The Shop Owner logs into the system, and the cashier may change at any time after the Shop Owner has logged in. This means that the access rights to data in the system is determined by the Shop Owner credentials and not by the cashier. In the future we may add several mechanisms for verifying a cashier (pin-code, id card swipe, etc.), but it is important to know that the current cashier is still just a property of the current sale, and not a User in the system as defined above.

For sales statistical purposes, sales are grouped by the cashier so that KPIs and performance can be measured per cashier.

Account owner

The account owner is a role in our system that gives a User access to read and change all data for an account. It should be thought of as an administrative role in the system that has the power to invite or dismiss shop owners and make basic configuration choices on behalf of the entire account.

Shop owner

The shop owner is, as the name suggests, the owner of a shop who only has access to configuration and data pertaining to the specific shop - and also read (not write) access to shared data for the entire account like the product database and configuration of currencies and taxes.

Pricing vocabulary

Pervasive in the Ka-ching system is naturally the idea of a sale and the pricing of products. We have very clear definitions of the involved vocabulary:

Retail price

This is the price of a product to be sold. The precise definition is 'the price that you would print on a label attached to the product'. This means that in countries using VAT, the retail price should include the VAT, while in countries using sales tax, the price would not include the sales tax.

Cost price

This is the price that the shop paid for the product. This price is ALWAYS without tax. In our system the cost price is an optional value, but in case it is entered, we can calculate the margins earned from the sales.

Sub total

This is the result of subtracting all discounts from the retail price. Like the retail price it includes any VAT and excludes any sales taxes.

Base price

This is the result of excluding all taxes from the sub total, so that it can be compared to the cost price and used to calculate margins. This means that in markets using only sales taxes, the base price and sub total will correspond.

Margin

This is the base price minus the cost price. It is optional since it can only be calculated if the cost price is present. It may become negative in case the product is sold cheaper than the cost price.

Total

This is the total including all taxes (both VAT and Sales Tax). This means that in markets where only VAT is used, the total and sub total will correspond.

Margin total

Since not all products have cost prices associated with them, we can only calculate the margins from the ones that do. So when calculating the ratio between the total and the margin, we need to keep the total for products where we can calculate margins separate from the totals where we can not. This consideration justifies the existence of the margin total which is equal to the total if the margin can be calculated and 0 if it cannot.

This means that when summarizing values, we can always get the correct margin ratio by taking the margin and divide it by the margin total. If we need to find out the total amount for which we cannot calculate this ratio (due to missing cost prices), we can subtract the margin total from the total.

Total VAT amount

Tax types are split into VAT and Sales Tax types (see section about Taxes), so this is the sum of the taxes that are of VAT type.

Total Sales Tax amount

This is the sum of the taxes that are of Sales Tax type.

Total Tax amount

This is the sum of all the taxes.

Sale

A sale may refer to the actual physical sale in progress in a shop, but more commonly it will refer to our representation of a sale when the sale is complete.

Note that in the Ka-ching system, a return of items is also represented using the Sale entity, but clearly marked as being a return, and with negated values for pricing and the like.

Taxes

Our product model supports any number of taxes to be added to a product simultaneously - or different taxes on different products. The rules for calculating taxes when multiple taxes are present are defined by standard mathematics.

Examples will be given below after our two main types of taxes have been explained:

VAT

VAT is a value added tax which is common in Europe. For VATs, the tax amount is included in the retail price of a product.

For instance a product with a retail price of 100 DKK with a VAT rate of 25% has a base price of 80 DKK and a VAT of 20 DKK (and a total price matching the retail price of 100 DKK).

Sales Tax

Sales Tax is a tax that is added at the point of sale. Sales Tax is used in the US. A product with a retail price of $100 and a Sales Tax of 17% will have a total price of $117 (and a base price matching the retail price of $100).

Multiple taxes - example

The rule for calculating taxes is very simple: "Taxes are never taxed." - meaning that you never apply a tax to an amount that already includes another tax amount. This means that we just need the base price - and this can be used to find the tax amount for each separate tax.

Let us imagine a market where four separate tax rates were applied when selling a product. Two separate sales taxes and two separate VATs (the names of the taxes are completely imaginary):

VTX: 10% VAT
MTX: 5% VAT
STX: 7% Sales Tax
XTX: 3% Sales Tax

In order to understand the tax calculation for this combination of taxes, imagine a product with a retail price of 230 DKK.

Remember that retail price is the price that you would print on a label and put on the physical product and that it thus includes all VAT taxes.

The total VAT is (10% + 5% = ) 15%, so the base price of the product is (230 / 1.15 = ) 200 DKK.

From the base price we can now find all tax amounts:

VTX: (200 * 10%) 20 DKK
MTX: (200 * 5%) 10 DKK
STX: (200 * 7%) 14 DKK
XTX: (200 * 3%) 6 DKK

So our summaries for the imaginary product are:

Base price: 200 DKK
VAT total: 30 DKK
Retail price: 230 DKK
Sub total: 230 DKK (same as retail price when we have no discounts)
Sales tax total: 20 DKK
Total: 250 DKK

To verify we can see that our retail price calculation was correct and that applying the total tax amount (10 + 5 + 7 + 3 =) 25% to the base price gives the total: 200 * 1.25 = 250 DKK

This may sound a bit complicated, but most likely you will only ever need to think about zero or one VAT rate or zero or one Sales Tax rate. :-)

Discounts

The Ka-ching system models discounts in a standard fashion while allowing discounts to come from a number of different sources.

One basic kind of discount is the manual discount which is manually added by the cashier at the time of the sale.

Another kind is the sale discount which is an easy-to-configure discount type that can be added directly when configuring the product in the Ka-ching Portal or when importing products to the Ka-ching system. Sale discounts give the products a new price while still showing the original price in the POS so that you can visualize the savings from the discount.

Finally we have the discount campaign rules where you can configure advanced rules for triggering automatic discounts. Such campaign rules could be: "Give a 10% discount when adding three or more items of a specific type to the basket".

Notice that only manual discounts can be edited and removed in the POS, the automatic ones are applied by system-defined rules and thus cannot be modified by the cashier.

Discount applications

Common for the discounts is how the discount is applied (or calculated). One is new price which basically changes the price of a product to the specified new price. Another application type is percentage which calculates the discount as a percentage of the price of the sold item. The amount off discount gives a fixed amount discount to an item.

Common for all application types is that fact that a discount cannot end up making the price negative. The price may become more expensive by applying a discount (and yes, there are use cases for this situation), but negatively priced products do not exist in the Ka-ching system, and as such any discount is capped to not making the product cheaper than 0.

Multiple discounts

Discounts are applied in order, and many discounts may modify the price of the same line item. For instance a product may have an automatic discount of 10%, but then get a manual new price discount and finally have an extra 5% discount that is applied to the entire basket. When we store records about our sales, we specify in detail how the discounts are applied to each line item.

Register Close Statements

When opening a register you enter an opening float (the amount of cash available in the register when it is opened). All sales, returns, cash drawer opens, etc. are registered and logged. When you close the register, all these events are stored as accumulated records for the total sales, total returns. All details of a single sale are accumulated into totals, so that the total taxes (grouped by tax type), total discounts, total cost prices etc. are represented in the Register Close Statement. Similar accumulated totals are also present grouped by the product group of the sold products.

Finally, the Register Close Statement contains information about reconciliations of any payment type for which reconciliation is necessary (for instance for cash).

Integration

An integration in the Ka-ching system can refer to an Import Integration, an Export Integration or any of the integrations used by the POS system, which we call Runtime Integrations.

For instance we could refer to a Product Import Integration, a Sales Export Integration or an E-commerce Product Search Integration.

Products and variants

A product is the representation of a physical product to be sold in the Ka-ching system. Products may have associated attributes that describe the details of the product. Note that not every product in the system is sellable. Some products may have variants associated with it. A variant may describe the size of a t-shirt or it's color. As such variants describe attributes of the product that sets it apart from others, but when you still logically think of the different variations as being the same product. This is of course a modelling choice - you can also model differently sized t-shirts as entirely separate products if you so wish.

Basket

In the POS, the products that we are selling are added to the current basket. You can think of this as a physical shopping basket, which is emptied when the customer makes a purchase, and the basket is ready for the next customer.

Line item

When adding products to a shopping basket, the representation of the products are referred to as line items. This means that a line item will typically correspond to some product information and a quantity. For instance a single line item may describe 10 Cappucinos.

External Order

An external order is a model describing an order or reservation that's been made in a different location than the pick up point. It is used when using our Reserve & Collect and Click & Collect features. An external order contains information about items, quantities, prices and discounts. It can also contain basic information about the customer who's pickup up the order as well as information about whether it's already been paid or not.