Klarna Docs - Subscriptions and on-demand
Subscriptions and on-demand

Everything you need to know about subscription and on-demand use cases.

Learn more about the use cases:

  • Subscriptions: allows customers to sign up for a subscription using Klarna as their payment method. Once complete, the payment preferences are tokenized and automatically used for renewals by the merchant using the token to create orders. Shoppers can manage their preferences at any time in the Klarna App.
  • On-demand: allows customers to add Klarna as a payment method in a digital wallet for one-click purchases of on-demand services. Shoppers can update their payment preferences at any time in the Klarna App.

Both use cases are facilitated by the "customer token".

A customer token is the combination of customer details and payment method data, together with a connection to a specific merchant.

A customer token helps speed up the checkout process. You only have to collect a customer's details and payment method information once to be able to reuse it for recurring orders. The customer doesn't need to take action as you can create orders on their behalf.

When you create an order using a customer token, we run a risk and fraud assessment to ensure that the customer can be offered credit for the order amount.

Customer tokens are stored in Klarna’s internal secure databases and no private information linked to customer tokens is shared externally.

You have to inform your customers that you're creating customer tokens for them and explain how you'll use the tokens to create orders. You can include this information in your store's terms and conditions.

You can create a customer token by sending a request through Klarna payments API.

A customer token can be either active, suspended, or canceled. When a token is created, its status is set to active by default.

You can use the Klarna payments API to perform three actions related to a customer token:

  1. Create an order in a payment session with intent set to tokenize or buy_and_tokenize.
  2. Check the details of a customer token.
  3. Cancel a customer token.

A customer token doesn't have an expiration date. It stays active until you cancel it.

Once you know that you'll not use a customer token anymore, for example, if your customer unsubscribes from your service or deletes their account, you can cancel a customer token using the Klarna payments API.

To check the status of a customer token, send a request using the Klarna payments API.

Yes, you can share a customer token between multiple Merchant IDs (MIDs) used by your company (for example, one MID dedicated to customer signup and another for placing orders). This is known as token clustering.

Initially, we assign a new customer token to the MID you got when you were onboarded to Klarna. If you want to link a customer token to other MIDs, contact Merchant support.

If you're using customer tokens in your checkout, you need to:

  1. Inform your customers of how you'll use the customer token for recurring purchases.
  2. Store customer tokens securely.
  3. Map your customers to customer tokens. Be able to correctly map your customer to our customer token ID.
  4. Trigger purchases from a customer token.

Only tokenizing or connecting it to the purchase flow? You can create a free-standing signup flow for customers to sign them up for tokens. You can also combine a purchase and create a customer token in the same session.

The information related to subscriptions is included in the subscription object inside the request's order_lines . This information lets us make better underwriting decisions and present the most fitting payment options (for example, monthly subscriptions vs. annual).

This object plays a key role in the post-purchase display of automatic payments in the Klarna app.  

Technical considerations:

  • Klarna doesn’t manage, maintain or validate uniqueness of the data points sent, meaning that any subscription name sent will be accepted, regardless of it existing on your side.
  • You have to include the subscription object in requests related to subscriptions whenever order lines are shared, that is, in the token creation flow (create session, load(), authorize(), and create order calls), and when you're creating an order using a customer token.
  • When using delayed captures in the Order management API, you have to include the subscription object when overriding order lines.
  • You are responsible for setting the logic of when new orders should be created using customer tokens. For example, if you're using customer tokens to charge your customers for recurring purchases, such as subscriptions, you have to create orders at intervals you specified when setting up the recurring payment order.

The subscription object contains the following elements:  

ElementFormatDescriptionRequired
namestringThe name of the subscription product. This string shouldn't include the name of the merchant or partner. The recommended format includes a subscription id and double curly brackets, for example Premium Membership {{12394832}} Y
intervalstringThe cadence unit for the subscription plan. Allowed values: DAY, WEEK, MONTH, YEARY
interval_countintegerThe number corresponding to the interval unitY

For example, if you want to charge for a subscription once a quarterly, set the value of interval to "MONTH" and interval_count to 3 . For a charge happening annually, set interval to "YEAR" and interval_count to 1 .

In the example for the name object in the table above, Premium Membership {{12394832}}, “Premium Membership” is the name of the subscription product and “12394832” is the identifier used for this subscription for this customer. Klarna may group multiple orders related to the same identifier for the same subscription product when presenting payment information to your customer.

A customer subscribed to a monthly streaming subscription for 15.99/month with a free 14-day trial.

Initiate a payment

JSON
POST /payments/v1/sessions 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Content-Type: application/json 
{ 
  "intent": "tokenize",
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE", 
  "order_amount": 0, 
  "order_tax_amount": 0, 

A sample create session request with the subscription object included in order_lines.

Create a customer token

JSON
POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac120002
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

A sample create customer token request with the subscription object included in order_lines.

A customer subscribed to regularly receive 2 different products at different time intervals: Ink cartridges every month and deodorant creme every 2 months.

Create a Klarna payments session for multiple subscription items

JSON
POST /payments/v1/sessions 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Content-Type: application/json 
{ 
  "intent": "buy_and_tokenize",
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE", 
  "billing_address": {
       	"given_name": "Thomas",

A sample create session request. Note two subscription objects, one per product and cadence, included in order_lines.

Create an order and complete the first purchase at checkout

JSON
POST /payments/v1/authorizations/<authorization_token>/order
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "purchase_country": "DE",
  "purchase_currency": "EUR",
  "billing_address": {
       	"given_name": "Thomas",
       	"family_name": "Testkunde",
       	"email": "thomas.testkunde@gmail.com",

Create an order using a customer token (month 1)

JSON
POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac122202
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

Create an order using a customer token (month 2)

JSON
POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac121102
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

Capture a request

JSON
POST /ordermanagement/v1/orders/{order_id}/captures
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "captured_amount": 999,
  "reference": "12345678", 
  "order_lines": [{ 
        "type": "digital", 
        "subscription": { 
        	"name": " Premium Monthly {{1234834}}", 

A sample capture request including the subscription object.

Cancel a customer token
You can cancel a customer token if it's no longer needed, for example, if a customer cancels their subscription.
Check the details of a customer token
Use the Klarna payments API to check the status and details of the payment method linked to a customer token.