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:
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.subscription
object when overriding order lines.The subscription object contains the following elements:
Element | Format | Description | Required |
---|---|---|---|
name | string | The 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 |
interval | string | The cadence unit for the subscription plan. Allowed values: DAY , WEEK , MONTH , YEAR | Y |
interval_count | integer | The number corresponding to the interval unit | Y |
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.
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
.
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.
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 .
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",
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",
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",
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.