Charge a subscription
Charge subscription renewals server-side using an existing Klarna customer token, on your billing schedule, with no customer interaction.
Overview
Charge a subscription renewal with a customer token you previously created. Renewals are merchant-initiated — your billing scheduler fires, your backend calls
createOrder on the customer token with the renewal amount and a subscription object matching signup, and Klarna creates the order without customer interaction. The customer is not present, so step-up does not run — failures are handled through your normal dunning process.Prerequisites
- An active customer token (check status), created at signup with a
subscriptionobject onorder_lines(intent: tokenizewithorder_amount: 0for free trial,intent: buy_and_tokenizefor paid signup). - Customer informed at signup that you will charge on the agreed cadence.
- Klarna Payments API basic-auth credentials.
Integration overview
sequenceDiagram
autonumber
participant Sched as Billing Scheduler
participant BE as Merchant Backend
participant Klarna as Klarna Payments API
Note over Sched: Renewal due
Sched->>BE: Fire renewal job
Note over BE: Look up customer_token<br/>and current renewal amount
BE->>Klarna: POST /customer-token/v1/tokens/{customerToken}/order
Note over BE,Klarna: order_lines with subscription object<br/>Klarna-Idempotency-Key per attempt
Klarna->>BE: 200 OK + order_id
Note over BE: Record period as paid<br/>Trigger capture if applicable
Integration details
Step 1: Prepare the renewal payload
Build the
createOrder payload using the same cadence and product information you supplied at signup. The renewal amount must match the current billing period, and the subscription object must be present on every renewal order_line — Klarna uses it for underwriting, fraud assessment, and the customer-facing display in the Klarna app.Collect the following per renewal:
| Field | Required | Description |
|---|---|---|
purchase_currency | Yes | ISO 4217 currency, matching the original token currency. |
order_amount | Yes | Total amount in minor units (for example, cents) for this renewal period. |
order_tax_amount | Yes | Tax portion of order_amount. Use 0 when not applicable. |
order_lines[] | Yes | At least one line item describing the subscription product being renewed. |
order_lines[].subscription | Yes | Object describing the subscription product. See the Subscription object section below. |
auto_capture | Recommended | Set to true unless you use delayed capture. |
merchant_reference1 | Recommended | Your internal reference for this renewal, used in settlement and reconciliation. |
Step 2: Call create order on the customer token
Send a 
with a unique
POST request to /customer-token/v1/tokens/{customerToken}/order with a unique Klarna-Idempotency-Key header. Reuse the same key when retrying the same logical renewal attempt after a network failure — never reuse it across distinct renewal attempts.This renewal is merchant-initiated and runs without customer presence: your billing scheduler fires from a backend job (a renewal cron, a trial-end timer) — the customer is not on any Klarna or merchant checkout surface. Step-up does not run on these charges, and any 4xx response is a dunning event handled through your existing dunning process. This framing applies to all three variants below.
Subscription object
Include the
subscription object inside every order_line for a recurring product on every renewal. Klarna uses it for underwriting, fraud assessment, and the customer-facing display in the Klarna app.| Field | Required | Description |
|---|---|---|
name | Yes | Product name including your internal subscription id, e.g. Premium Monthly {{1234834}}. Displayed to the customer in the Klarna app. |
interval | Yes | One of DAY, WEEK, MONTH, YEAR. Must match what you submitted at signup. |
interval_count | Yes | Number of interval units between renewals. Must match what you submitted at signup. |
Variants
Three renewal patterns share this endpoint:
| Variant | When it fires | Special considerations |
|---|---|---|
| First paid charge after a free trial | When the agreed free trial ends (typically 7, 14, or 30 days) — the token was created at signup with intent: tokenize and order_amount: 0, so no funds moved yet. | Charge the full first renewal amount — the zero-amount tokenization happened at signup, not at this charge. Use the same subscription cadence the customer committed to at signup. |
| Standard recurring renewal | On the schedule defined at signup (interval + interval_count). | Amount and line items reflect the current billing period and may differ from the signup amount (price changes, proration, upgrades). |
| Multiple subscription products on a single token | When one token covers multiple products with different cadences (e.g. a monthly plan and an annual add-on). | Send separate createOrder calls — one per product per billing date — each with the matching subscription object. Do not combine cadences into a single request. |
First paid charge after a free trial
JSON
1
2
3
4
5
6
7
8
9
10
POST /customer-token/v1/tokens/{customerToken}/order
Authorization: Basic <credentials>
Klarna-Idempotency-Key: c29f321c-8f38-11ec-b909-0242ac120003
Content-Type: application/json
{
"auto_capture": true,
"purchase_country": "DE",
"purchase_currency": "EUR",
"locale": "de-DE",Standard recurring renewal
JSON
1
2
3
4
5
6
7
8
9
10
POST /customer-token/v1/tokens/{customerToken}/order
Authorization: Basic <credentials>
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac120002
Content-Type: application/json
{
"auto_capture": true,
"purchase_country": "DE",
"purchase_currency": "EUR",
"locale": "de-DE",Multiple subscription products on a single token
When one token covers multiple subscription products with different cadences, issue parallel
createOrder calls — one per product per billing date, each with its own Klarna-Idempotency-Key and merchant_reference1. The example below is one of those calls (the monthly plan); you would fire a separate call for the annual add-on on its own billing day.JSON
1
2
3
4
5
6
7
8
9
10
POST /customer-token/v1/tokens/{customerToken}/order
Authorization: Basic <credentials>
Klarna-Idempotency-Key: d39f321c-8f38-11ec-b909-0242ac120004
Content-Type: application/json
{
"auto_capture": true,
"purchase_country": "DE",
"purchase_currency": "EUR",
"locale": "de-DE",Step 3: Handle the response
Klarna evaluates the renewal and returns one of the outcomes below.
| Result | What you receive | Next steps |
|---|---|---|
| 200 OK | order_id, fraud_status: ACCEPTED, authorized_payment_method, redirect_url | Record the period as paid. Store order_id. Trigger capture if you did not set auto_capture: true. |
4xx (most commonly 403 with error_code) | error_code, error_messages, correlation_id | Treat as a dunning event. Notify the customer through your standard dunning process and retry on your normal schedule. See validations in Klarna Payments for code-by-code handling. |
| 5xx | Transient error | Retry the same request with the same Klarna-Idempotency-Key. Do not generate a new key on retry. |
JSON
1
2
3
4
5
6
7
8
{
"order_id": "3eaeb557-5e30-47f8-b840-b8d987f5945d",
"redirect_url": "https://payments.klarna.com/redirect/...",
"fraud_status": "ACCEPTED",
"authorized_payment_method": {
"type": "invoice"
}
}Subscription renewals are merchant-initiated and must not use the step-up flow. If a renewal fails, handle it as dunning — do not redirect the customer into a step-up session from your renewal job. When you need to recover a failed subscription (for example, the customer needs to confirm a new card), use the on-demand charge guides at the customer's next interaction instead.
Step 4: Capture and reconcile
If you set when you deliver the next service period. Use
auto_capture: true, the renewal is captured immediately. Otherwise, call capture order when you deliver the next service period. Use merchant_reference1 to reconcile the renewal against your billing system in settlement reports.Do's and don'ts
| Do | Don't |
|---|---|
Include the subscription object on every renewal order_line, matching the cadence agreed at signup. | Omit the subscription object on renewals — it affects underwriting, fraud assessment, and the customer's Klarna app display. |
Generate a unique Klarna-Idempotency-Key per renewal attempt. Reuse it only when retrying the same attempt after a network failure. | Reuse an idempotency key across distinct renewal attempts (for example, the next billing period). |
| Treat 4xx responses as dunning events handled through your existing dunning process. | Redirect the customer into a step-up flow from a renewal job — the customer is not present. |
Use a separate createOrder call per product when one token covers multiple subscription products. | Combine multiple cadences into a single createOrder request. |
Related guides
- Customer token — what a customer token is and how to create one