Mixed payment use cases

Charge a subscription or add-on with an existing Klarna customer token after a mixed checkout where the customer paid a one-time item and Klarna tokenized a Pay Now funding source.

Overview

Charge a subscription or add-on after a mixed checkout. In a mixed checkout, the customer pays a one-time item with Klarna and you tokenize a recurring/add-on payment method in the same session using intent: buy_and_default_tokenize. This guide covers follow-up charges (subscription renewals or on-demand add-ons) on the resulting token. Subscription renewals are merchant-initiated and do not run step-up; on-demand add-ons run with the customer present, and if Klarna returns step_up_id, switch to the on-demand SDK or HPP charge guide.

What gets tokenized in a mixed checkout. Klarna tokenizes a Pay Now funding source — not the payment method the customer selected for the one-time item. Example: if the customer paid with Pay in 4 backed by a card, Klarna tokenizes Pay Now on the same card. If the customer chose an option without a funding source (e.g. Pay Later Invoice), Klarna tokenizes Pay Later 30. Account for this when sizing follow-up amounts.

Prerequisites

A mixed checkout completed with intent: buy_and_default_tokenize — one-time item paid, first order created.
A customer token issued via purchaseToken, mapped to your customer record, status active (check status).
Klarna Payments API basic-auth credentials.

Integration overview

sequenceDiagram autonumber participant Trigger as Add-on trigger / Renewal scheduler participant BE as Merchant Backend participant Klarna as Klarna Payments API Note over Trigger: Earlier — mixed checkout completed: one-time item paid, customer_token issued Trigger->>BE: Fire follow-up charge Note over BE: Look up customer_token and follow-up amount (add-on or subscription) BE->>Klarna: POST /customer-token/v1/tokens/{customerToken}/order Note over BE,Klarna: order_lines = follow-up only (NOT the one-time item) Klarna-Idempotency-Key per attempt Klarna->>BE: 200 OK + order_id Note over BE: Fulfill add-on / record period as paid Trigger capture if applicable

Integration details

Step 1: Prepare the follow-up payload

Build the createOrder payload using the follow-up line item only — the add-on or subscription you are charging now. Do not include the one-time line item that was already paid at checkout.

Collect the following:

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 follow-up charge.
`order_tax_amount`	Yes	Tax portion of `order_amount`. Use `0` when not applicable.
`order_lines[]`	Yes	At least one line item describing the add-on or subscription being charged now.
`order_lines[].subscription`	Conditional	Required when the line item is a recurring product. See the Charge a subscription guide for the field definitions.
`auto_capture`	Recommended	Set to `true` unless you use delayed capture.
`merchant_reference1`	Recommended	Your internal reference for this follow-up charge, used in settlement and reconciliation.

Step 2: Call create order on the customer token

Send a POST request to /customer-token/v1/tokens/{customerToken}/order

with a unique Klarna-Idempotency-Key. Reuse the same key when retrying the same logical attempt after a network failure — never reuse it across distinct follow-up charges. Set merchant_reference1 to a value your billing system can correlate with this charge in settlement reports.

This follow-up charge is merchant-initiated and runs without customer presence on a Klarna checkout surface: your backend fires it on its own schedule (a renewal cron job, a trial-end timer) or in response to a non-checkout trigger (a subscription-engine webhook, an internal usage event). Step-up does not run as part of the createOrder request, and any 4xx response is a dunning event handled through your existing dunning process. This framing applies to all three variants below.

Variants

Three follow-up patterns share this endpoint:

Variant	When it fires	Special considerations
Subscription follow-up	First subscription charge after the mixed checkout — typically the day after fulfillment of the one-time item, or whenever the agreed billing date arrives.	Include the `subscription` object with the cadence the customer agreed to at signup. Every subsequent renewal on the same cadence is handled by Charge a subscription.
Subscription after free trial	When an agreed free trial ends (typically 7, 14, or 30 days) — no charges fire during the trial.	Use the same `subscription` cadence the customer committed to at signup. Trial duration is a billing-side concept, not a payload field. The customer is not present at trial-end — treat any 4xx as a dunning event.
On-demand add-on	Customer-triggered add-on tied to the original one-time item (consumables, accessories, one-off services).	Set `step_up: SUPPORTED`, register `merchant_urls.authorization`, and omit the `subscription` object. If Klarna returns `step_up_id`, switch to Charge an on-demand payment via SDK or via HPP and continue from Step 4 of that guide — the SDK must already be loaded on the page where the add-on is triggered.

JSON

1 2 3 4 5 6 7 8 9 10

POST /customer-token/v1/tokens/{customerToken}/order
Authorization: Basic <credentials>
Klarna-Idempotency-Key: d49f321c-8f38-11ec-b909-0242ac120005
Content-Type: application/json

{
  "auto_capture": true,
  "purchase_country": "DE",
  "purchase_currency": "EUR",
  "locale": "de-DE",

Step 3: Handle the response

Klarna evaluates the follow-up charge 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`	Fulfill the add-on or record the subscription period as paid. Store `order_id`. Trigger capture if you did not set `auto_capture: true`.
4xx with `step_up_id`	`step_up_id`, `error_code: UNAVAILABLE_PAYMENT_METHOD`, `fraud_status: REJECTED`	The customer is present for an on-demand add-on. Switch to Charge an on-demand payment via SDK or via HPP and continue from Step 4 of that guide. For subscription renewals, treat as a dunning event — the customer is not present.
Other 4xx	`error_code`, `error_messages`, `correlation_id`	For add-ons (customer present), return the customer to the add-on surface with a clear failure message. For subscription renewals, treat as a dunning event. See validations in Klarna Payments.
5xx	Transient error	Retry with the same `Klarna-Idempotency-Key`. Do not generate a new key on retry.

Sample success response

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"
  }
}

Step 4: Capture and reconcile

If you set auto_capture: true, the follow-up charge is captured immediately. Otherwise, call capture order API

when you deliver the add-on or service period.

Use merchant_reference1 to reconcile against your billing system in settlement reports.

Do's and don'ts

Do	Don't
Pass only the follow-up line item (add-on or subscription) in the `createOrder` request.	Re-charge the one-time item that was already paid at checkout.
Include the `subscription` object when charging a recurring add-on or subscription.	Omit the `subscription` object on recurring charges — it affects underwriting and the Klarna app display.
Switch to the on-demand SDK or HPP guide if you receive `step_up_id` for an add-on charge while the customer is present.	Try to handle step-up from your scheduler or background renewal job — the customer is not present.
Generate a unique `Klarna-Idempotency-Key` per follow-up charge attempt.	Reuse an idempotency key across distinct follow-up charges.
Use Charge a subscription for ongoing subscription renewals on the same cadence.	Reuse this guide for every subscription renewal — this one covers the first follow-up after mixed checkout.