Sharing Subscription Details
Kustom Checkout (KCO)'s automatic payments support subscription use cases. When creating an order, KCO requires a specific "subscription" field to be sent with the order lines.
This field is crucial for KCO's underwriting and presenting appropriate payment options. It's also vital for displaying automatic payments in the Klarna app.
Technical Considerations
- KCO doesn't validate the uniqueness of subscription data. Any subscription name will be accepted.
- The "subscription" object must be included with order lines during token creation and order creation using a token.
- For "delayed captures" using the Order Management API, the subscription object is required if order lines are overridden.
Subscription Object Elements
The subscription object contains the following elements:
| Element | Format | Description | Required |
|---|---|---|---|
| name | string | The subscription product name. Avoid including merchant or partner names. Use a format like: Premium Membership {{12394832}} where 12394832 is a unique identifier. | Yes |
| interval | string | The subscription's cadence unit. Valid values: "DAY", "WEEK", "MONTH", "YEAR". | Yes |
| interval_count | int | The corresponding number for the interval unit. | Yes |
For example, a quarterly subscription would use "MONTH" and interval_count of 3. An annual subscription would use "YEAR" and interval_count of 1.
Example 1: Monthly Streaming Subscription
A monthly streaming subscription for $15.99 with a 14-day free trial. The 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,
"unit_price": 0,
"tax_rate": 0,
"total_amount": 0,
"total_discount_amount": 0,
"total_tax_amount": 0
}]Example 2: Fixed Amount Multiple Goods
A consumer subscribes to ink cartridges monthly and deodorant every two months.
"order_lines": [
{
"type": "physical",
"subscription": {
"name": "Savings Subscription {{1234834}}",
"interval": "MONTH",
"interval_count": 1
},
"reference": "19-402",
"name": "Prater Ink Cartridges",
"quantity": 1,
"unit_price": 360,
"tax_rate": 0,
"total_amount": 360,
"total_discount_amount": 0,
"total_tax_amount": 0
},
{
"type": "physical",
"subscription": {
"name": "Savings Subscription {{1822731}}",
"interval": "MONTH",
"interval_count": 2
},
"reference": "19-402",
"name": "Greenstore Deo Cream",
"quantity": 1,
"unit_price": 790,
"tax_rate": 0,
"total_amount": 790,
"total_discount_amount": 0,
"total_tax_amount": 0
}
]Additional examples of creating customer token order requests and capture requests with the subscription object are also provided in the documentation.