Klarna Docs - Update ongoing order

Update ongoing order

Handle cart updates and changes of country and or locale (language)

How it’s done

If the consumer makes changes to the basket, e.g. by navigating back to your catalog, you must update the existing Klarna Checkout order with the new basket and order amounts. If the consumer changes the country/language we recommend you update the purchase country, locale and purchase currency to reflect these changes. If the changes are made on the same page as the checkout, you must suspend-update-resume Klarna Checkout in order for the snippet to update visually. Klarna Checkout offers API callbacks (url endpoints that Klarna can POST information to) for change events inside the snippet. Example: if the consumer changes the (billing/shipping) country inside Klarna Checkout, you can listen to that event and update your shop country/currency as well if required.

You should keep track of the Klarna order_id associated with the current customer to avoid creating a new order every time the customer loads the checkout page. This will allow the customer to reload the checkout page without having to re-enter any information they have already provided.

When the customer loads the checkout page and have a Klarna order_id associated with their session you should fetch the order from Klarna. If the order content have changed you should update the order.

  • Klarna checkout orders are only valid for 48 hours after merchant update or client interaction and expire after that. This expiration is normal and Klarna will respond with a HTTP 404.
  • If you get a HTTP 4XX or 5XX or any other type of error, you should create a new order.

Retrieve an Order

Use the checkout order_id to fetch the order from Klarna.

Read Order Request
HTTP
GET /checkout/v3/orders/<order_id>
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

Read Order Response

JSON
{
  "order_id": "8cf27b55-53e8-6aba-9fb4-7c692e56ddee",
  "status": "checkout_complete",
  "purchase_country": "gb",
  "purchase_currency": "GBP",
  "locale": "en-GB",
  "billing_address": {
    "given_name": "Testperson-se",
    "family_name": "Approved",
    "email": "Testperson-se@test.klarna.com",

Update the Order

You should update the checkout order to reflect the changes that the customer has made to the cart. The request below will update the order with adding another item to the card.

Once the customer has provided any data in the checkout iframe, updates to the billing_address and shipping_address will be ignored (without generating an error).

Updating Order Request

JSON
POST /checkout/v3/orders/<order_id>
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
"order_amount": 756682,
"order_tax_amount": 151336,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",

Updating Order Response

JSON
{
"order_id": "1203c28c-f101-765f-bed8-f57a2d5e83e0",
"status": "checkout_incomplete",
"purchase_country": "se",
"purchase_currency": "sek",
"locale": "en-GB",
"billing_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",

Note: Find out more about the different fields in the cart items list in the API Reference.

Update an Ongoing Checkout Order

If you want to update an order while the customer is on the checkout page, you will need to suspend the checkout, update the order, and then resume the checkout to make sure the information shown in the checkout is up to date.

The flow is visualized in the chart below:

Suspend the Checkout

Suspending the checkout puts it in a waiting state, preventing customer input. A loading icon is rendered on top of the iframe indicating to the customer that the checkout is loading.

You can do this by issuing a Javascript command, as per the code example below:

JAVASCRIPT
window._klarnaCheckout(function (api) {
    api.suspend();
});

Update the Order

Update the order as you did in the example above.

Resume the Checkout

Resuming the checkout forces it to fetch the most recent order data from Klarna. The loading indicator will disappear, the form will become enabled. The amount presented in the checkout will now reflect the new order total.

JAVASCRIPT
window._klarnaCheckout(function (api) {
    api.resume();
});