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 firstname.lastname@example.org
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.
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 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.
The Ka-ching system supports selling products through a variety of channels - and the number of channels may expand over time. One channel is the POS system, meaning that all products in this channel will appear in the POS. Another channel is
online which basically represents products that are sold through an e-commerce channel. When we add customer centric apps (intended for your customers and end users), the
customer-centric channel will also be added.
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.
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 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
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
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.
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:
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.
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.
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.
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.
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
This is the total including all taxes (both VAT and Sales Tax). This means that in markets where only VAT is used, the
sub total will correspond.
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 VAT amount
Tax types are split into
Sales Tax types (see section about Taxes), so this is the sum of the taxes that are of
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 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.
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 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 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.
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. :-)
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
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.
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.
Register Close Statement contains information about reconciliations of any payment type for which reconciliation is necessary (for instance for
For instance we could refer to a
Product Import Integration, a
Sales Export Integration or an
E-commerce Product Search Integration.
Products and variants
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.
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.
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.