KCO’s automatic payments provides our partners with support for the acquisition of payments for their subscription use cases. When an order gets created in this context, KCO requires a specific field to be sent along the order lines.
The subscription object lets KCO make better underwriting decisions and present more appropriate payment options (like monthly subscriptions vs. annual), it is also leveraged and plays a vital role in the post-purchase display of automatic payments in the Klarna app.
Technical considerations:
- KCO doesn’t manage, maintain or validate unicity of the data points sent, meaning that any subscription name sent will be accepted, regardless of it existing on your side
- subscription should be included whenever order lines are shared - both in the token creation flow and the creation of an order using a token.
- When using “delayed captures” with our Order Management API, you will need to include the subscription object if you override order lines.
The subscription object contains the following elements:
| Element | Format | Description | Required |
|---|---|---|---|
| name | string | The name of the subscription product. This string should not include the name of the merchant or partner. The recommended format would include a subscription id and double curly brackets as follows: Premium Membership {{12394832}} | Y |
| interval | string | The cadence unit for the subscription plan. Allowed values: "DAY", "WEEK", "MONTH", "YEAR" | Y |
| interval_count | int | The corresponding number for the interval unit. | Y |
To demonstrate how to use set the values in the object, for a subscription that is charged quarterly, the value of the interval would be "MONTH" and the interval_count to 3. For an annually charged subscription, the interval would be "YEAR" and the interval_count would be 1.
In the recommended format example for the name element in the table above, Premium Membership {{12394832}}, “Premium Membership” is the name of the subscription product and “12394832” the identifier used for this subscription for this consumer. KCO may group multiple orders related to the same identifier for the same subscription product when presenting payment information to the consumer.
A consumer has subscribed to a monthly streaming subscription for 15.99 every month. The customer has a free 14 day trial to start.
Order lines include the subscription object
"order_lines": [{
"type": "digital",
"subscription": {
"name": "Premium Monthly {{1234834}}",
"interval": "MONTH",
"interval_count": 1
}
"reference": "19-402",
"name": "Streaming Service Monthly - Free Trial",
"quantity": 1, Order lines expected when creating automatic payments:
Create Customer Token Order Request with the Subscription Object
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 consumer has subscribed to regularly receive 2 different goods with different rhythms: ink cartridges every month and deodorant creme every 2 months.
Multiple Subscription Items
"order_lines": [{
"type": "physical",
"subscription": {
"name": "Savings Subscription {{1234834}}",
"interval": "MONTH",
"interval_count": 1
}
"reference": "19-402",
"name": "Prater Ink Cartridges",
"quantity": 1, Create Customer Token Order Request for month 1
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 Customer Token Order Request for month 2
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",Sample Capture Request with the subscription object:
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}}",