Klarna Docs - Sharing Subscription Details with Klarna

Sharing subscription details with Klarna.

When sharing order information related to a subscription, you need to provide some additional information about the order.

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.

Related articles
Set up a recurring payment order.
Once Klarna authorizes the purchase, it's time to create an order and complete the payment.