How to handle tax correctly in Klarna Payments

When defining the order towards Klarna there are fields to use for tax handling. This article will present how to use these correctly and what validations there are.

Date: 11.07.2019

Why do we care?

To offer customers a clear view of total order amount, it is recommended to always include any tax amounts in the order details shared with Klarna. To ensure that all calculations are done correctly, tax validation is offered by Klarna.

Below you can find in-depth descriptions of how this validation is done, to ensure your own validation is aligned with Klarna’s.

Best practice of handling tax - EU vs US

Based on customer preferences and expectations being different in EU versus US, our recommendation of how you should report taxes to our API is different for these markets.

Transmitting tax in the EU

If you are using Klarna in any European market it is recommended that:

  1. tax_rate and tax_amount are to be transmitted for each order line.
  2. Calculation of tax amounts on order line level and order level need to be within the allowed deviation, as seen below.
  3. Use the field order_tax_amount to sum sum all total_tax_amount on order line level.

EU example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
  {
    "order_amount": 62400,
    "order_tax_amount": 12480,
    "order_lines": [
      {
        "type": "physical",
        "reference": "19-402",
        "name": "Battery Power Pack",
        "image_url": "https://www.exampleobjects.com/logo.png",
        "product_url": "https://www.estore.com/products/f2a8d7e34"
        "quantity": 1,
        "tax_rate": 2000,
        "total_amount": 59500,
        "total_tax_amount": 11900,
        "unit_price": 59500,
        "type": "physical"
      },
      {
        "quantity": 1,
        "tax_rate": 2000,
        "total_amount": 2900,
        "total_tax_amount": 580,
        "unit_price": 2900,
        "type": "shipping_fee"
      }
    ]
  }

Transmitting tax in the US

If you are using Klarna in the United States it is recommended that:

Tax amount is transmitted as an additional order line.

  • Note that it can be multiple order lines for different tax types.
    • Order line type is set to sales_tax
  • Order line name should be “Tax” or “Sales Tax”
  • order_tax_amount is the total_amount of sales_tax order line
  • order_amount is the sum of the total_amount from each order line, plus the order_tax_amount
  • There is no tax rate present in any order line

US sample create session call with tax:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "purchase_country": "US",
    "purchase_currency": "USD",
    "locale": "en-US",
    "order_amount": 21000,
    "order_tax_amount": 1000,
    "order_lines": [
        {
            "type": "physical",
            "reference": "19-402",
            "name": "Battery Power Pack",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_url": "https://www.estore.com/products/f2a8d7e34"
            "quantity": 1,
            "unit_price": 20000,
            "total_amount": 20000
        },
        {
            "type": "sales_tax",
            "name": "Tax",
            "quantity": 1,
            "unit_price": 1000,
            "total_amount": 1000
        }
    ]
}

Tax validation logic

There are two ways to implement taxes in klarna’s products. The global way of having it as a part of every single item and summarize on order level. As well as the US standard of having it as a separate item.

The global way validates taxes at order and item level.

At order level, the calculated total amount including tax must be within error tolerance value ±Items Quantity.

sum(items total tax amount) - sum(items) <= total tax amount <= ( sum(items) total tax amount sum(items)) At item level the value of calculated tax rate must be within error tolerance ±1. All item’s validation must be valid to create an order:

(calculated tax rate - 1) <= tax rate <= (calculated tax rate + 1)

where:

calculated tax rate = 100 * total tax amount / (total amount - total tax amount)

Examples

Order with 2 items accepted:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
"order_amount": 62400,
"order_tax_amount": 12480,
"order_lines": [
  {
    "quantity": 1,
    "reference": "19-402",
    "name": "Battery Power Pack",
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"
    "tax_rate": 2000,
    "total_amount": 59500,
    "total_tax_amount": 11900,
    "unit_price": 59500,
    "type": "physical"
  },
  {
    "quantity": 1,
    "tax_rate": 2000,
    "total_amount": 2900,
    "total_tax_amount": 580,
    "unit_price": 2900,
    "type": "shipping_fee"
  }
]
}
      ```

**Validation at order level**
> (11900 + 580) - 2 <= 12.480 <= (11900 + 580) + 2
>
> 12480 - 2 <= 12.480 <= 12480 + 2
>
> **ACCEPTED**

**Validation at item level**
> *Item 1*
>
> Calculated tax rate = (119 * 100) / (714 - 119)
>
> Calculated tax rate = 20
>
> 2000 - 1 <= 2000 <= 2000 + 1
>
> *ACCEPTED*
>
> *Item 2*
>
> Calculated tax rate = (5.8 * 100) / (34.8 - 5.8)
>
> Calculated tax rate = 20
>
> 2000 - 1 <= 2000 <= 2000 + 1
>
> **ACCEPTED**

Order with 2 items rejected at item level:
```js
{
"order_amount": 62400,
"order_tax_amount": 12480,
"order_lines": [
{
  "quantity": 1,
  "reference": "19-402",
  "name": "Battery Power Pack",
  "image_url": "https://www.exampleobjects.com/logo.png",
  "product_url": "https://www.estore.com/products/f2a8d7e34"
  "tax_rate": 2500,
  "total_amount": 59500,
  "total_tax_amount": 11900,
  "unit_price": 59500,
  "type": "physical"
},
{
  "quantity": 1,
  "tax_rate": 2500,
  "total_amount": 2900,
  "total_tax_amount": 580,
  "unit_price": 2900,
  "type": "shipping_fee"
}
]
}

Validation at order level

(11900 + 580) - 2 <= 12.480 <= (11900 + 580) + 2

12480 - 2 <= 12.480 <= 12480 + 2

ACCEPTED

Validation at item level

Calculated tax rate = (119 * 100) / (714 - 119)

Calculated tax rate = 20

2000 - 1 <= 2500 <= 2000 + 1

REJECTED

Response when validation is not success

If the order is not valid the response will include the field or value incorrect.

The sales tax might change from the point the order is created to the time the order is shipped (ie order placed on 28th of the month, but doesn’t ship until the 3rd of the next month)

  1. Create order with tax rate which is valid at that point
  2. If tax rate is different (most likely lower) at the time of shipment, update the order
  3. Most retailers don’t charge a higher tax, but rather side with the customer and only charge what’s quoted at the time of placing an order. However, (it’s a law) they do charge lesser amount if the tax is lower at the time of shipment.
  4. Klarna does a new risk check when the order is updated. If this check fails the merchant needs to accept that he can not capture the increased tax amount.
  5. If Klarna accepts the update, the merchant can capture the increased amount