Incremental onboarding

Incremental onboarding lets Acquiring Partners add new resources to existing Klarna accounts without rebuilding them, keeping current setups unchanged through exact matching and idempotent updates.

Overview

The onboard API

operation can be called multiple times for the same Partner Account to create new resources over time. When you call onboard API

with an existing partner_account_reference, Klarna identifies the existing Partner Account and adds any new resources included in the payload, such as Brands, Store Groups, Stores, Payment Accounts, or Business Entities.

This capability enables you to:

Start with minimal Partner data and add details progressively
Expand existing Partner Accounts as Partners grow their business
Adapt to Partners whose information becomes available in stages
Add new markets, stores, or legal entities without recreating the entire account structure

How it works

When calling onboard API

with an existing partner_account_reference:

1.
Klarna identifies the existing Partner Account instead of creating a new one
2.
New resources (with references that don't exist in Klarna) are created and added to the Partner Account
3.
Existing resources (with references that already exist) must have an identical payload to what is stored. If the payload differs, the request fails with a 409 Conflict error
4.
Missing resources are left unchanged—you don't need to resend existing resources

Key rules

Exact matching required: If you include an existing resource reference, all fields must match exactly what Klarna has stored
Immutable fields remain immutable: Data points listed in Data immutability cannot be modified by calling onboard again
Partial payloads allowed: Only send the new resources you want to add
Idempotency applies: Use a unique Klarna-Idempotency-Key for each logical onboarding request

Example scenario: Progressive Partner expansion

This example demonstrates how a Partner Account evolves through multiple onboard API

calls as a Partner's business expands from a single store to a multi-brand, multi-market operation.

Initial state: Simple retail setup

Scenario: TechGear starts as a small electronics retailer with one online store in the United States.

First onboard call:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "TECHGEAR001",
  "partner_account_name": "TechGear",
  "partner_account_contact": {
    "given_name": "Sarah",
    "family_name": "Chen",
    "email": "sarah@techgear.com",
    "phone": "+15555551234"
  },
  "partner_business_entities": [

Result: Partner Account created with one Brand, one Store Group, one Store, one Business Entity, and one Payment Account.

flowchart TB subgraph ACCT[Partner Account: TechGear] CON[Contact: Sarah Chen] end subgraph PBE1[Partner Business Entity] LE1[Legal Entity: TechGear Inc.] MCC1[MCC: 5732] end subgraph BRAND1[Brand] B1[TechGear] end subgraph SG1[Store Group: TG-SG-US] S1[Store: techgear-us-web Website] end PROD[Payment Product] PA1[Payment Account: TG-PA-001] ACCT --> PROD PROD --> PA1 PA1 --> PBE1 PA1 --> SG1 SG1 --> BRAND1

Second onboard call: Adding a new store

Scenario: TechGear opens a physical retail location in San Francisco. They want to add this store to their existing Partner Account.

Second onboard call (only includes new resources):

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "TECHGEAR001",
  "partner_account_name": "TechGear",
  "store_groups": [
    {
      "store_group_reference": "TG-SG-US",
      "brand_reference": "BRAND-TECHGEAR",
      "stores": [
        {
          "store_reference": "techgear-sf-store",

Key points:

The same partner_account_reference is used to identify the existing Partner Account
Only the new Store is included in the payload
The store_group_reference and brand_reference already exist and are being referenced
The existing Store (techgear-us-web) is not included—it remains unchanged

Result: New physical store added to the existing Store Group.

flowchart TB subgraph ACCT[Partner Account: TechGear] CON[Contact: Sarah Chen] end subgraph PBE1[Partner Business Entity] LE1[Legal Entity: TechGear Inc.] MCC1[MCC: 5732] end subgraph BRAND1[Brand] B1[TechGear] end subgraph SG1[Store Group: TG-SG-US] S1[Store: techgear-us-web Website] S2[Store: techgear-sf-store Physical Store] end PROD[Payment Product] PA1[Payment Account: TG-PA-001] ACCT --> PROD PROD --> PA1 PA1 --> PBE1 PA1 --> SG1 SG1 --> BRAND1 style S2 fill:#d4edda

Third onboard call: Expanding to Europe

Scenario: TechGear expands to Europe, establishing a new legal entity in Germany to comply with local regulations. They launch a new website for the European market.

Third onboard call (includes new Business Entity, Payment Account, and Store Group):

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "TECHGEAR001",
  "partner_account_name": "TechGear",
  "partner_business_entities": [
    {
      "partner_business_entity_reference": "TG-EU-001",
      "legal_registered_entity_name": "TechGear GmbH",
      "legal_registration_country": "DE",
      "enabled_merchant_category_codes": ["5732"]
    }

Key points:

A new Business Entity (TG-EU-001) is created for the German legal entity
A new Payment Account (TG-PA-002) is created linked to the new Business Entity
A new Store Group (TG-SG-EU) is created for the European market
The existing Brand (BRAND-TECHGEAR) is referenced for the new Store Group
US Business Entity, Payment Account, and Stores remain unchanged

Result: European expansion complete with new legal entity, payment account, and store group.

flowchart TB subgraph ACCT[Partner Account: TechGear] CON[Contact: Sarah Chen] end subgraph PBE1[Partner Business Entity #1] LE1[Legal Entity: TechGear Inc.] MCC1[MCC: 5732] end subgraph PBE2[Partner Business Entity #2] LE2[Legal Entity: TechGear GmbH] MCC2[MCC: 5732] end subgraph BRAND1[Brand] B1[TechGear] end subgraph SG1[Store Group: TG-SG-US] S1[Store: techgear-us-web Website] S2[Store: techgear-sf-store Physical Store] end subgraph SG2[Store Group: TG-SG-EU] S3[Store: techgear-eu-web Website] end PROD[Payment Product] PA1[Payment Account: TG-PA-001] PA2[Payment Account: TG-PA-002] ACCT --> PROD PROD --> PA1 PROD --> PA2 PA1 --> PBE1 PA1 --> SG1 PA2 --> PBE2 PA2 --> SG2 SG1 --> BRAND1 SG2 --> BRAND1 style PBE2 fill:#d4edda style PA2 fill:#d4edda style SG2 fill:#d4edda style S3 fill:#d4edda

Fourth onboard call: Launching a new brand

Scenario: TechGear launches "GearPro," a premium brand targeting enterprise customers. They create a separate website for this brand in the US market, using the existing US legal entity.

Fourth onboard call (includes new Brand and Store Group):

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "TECHGEAR001",
  "partner_account_name": "TechGear",
  "brands": [
    {
      "brand_reference": "BRAND-GEARPRO",
      "display_name": "GearPro",
      "element": {
        "logo_url": "https://gearpro.com/logo.png"
      }

Key points:

A new Brand (BRAND-GEARPRO) is created
A new Store Group (TG-SG-GEARPRO) is created for the new brand
The new Store Group uses the same Payment Account (TG-PA-001) as the existing TechGear brand, since it operates under the same US legal entity
All existing resources remain unchanged

Result: New brand and store group added to the existing Partner Account. The new Stores can be used during transaction to override the default_store_group set on the Payment Account.

flowchart TB subgraph ACCT[Partner Account: TechGear] CON[Contact: Sarah Chen] end subgraph PBE1[Partner Business Entity #1] LE1[Legal Entity: TechGear Inc.] MCC1[MCC: 5732] end subgraph PBE2[Partner Business Entity #2] LE2[Legal Entity: TechGear GmbH] MCC2[MCC: 5732] end subgraph BRAND1[Brand: TechGear] B1[TechGear] end subgraph BRAND2[Brand: GearPro] B2[GearPro] end subgraph SG1[Store Group: TG-SG-US] S1[Store: techgear-us-web Website] S2[Store: techgear-sf-store Physical Store] end subgraph SG2[Store Group: TG-SG-EU] S3[Store: techgear-eu-web Website] end subgraph SG3[Store Group: TG-SG-GEARPRO] S4[Store: gearpro-us-web Website] end PROD[Payment Product] PA1[Payment Account: TG-PA-001] PA2[Payment Account: TG-PA-002] ACCT --> PROD PROD --> PA1 PROD --> PA2 PA1 --> PBE1 PA1 --> SG1 PA2 --> PBE2 PA2 --> SG2 SG1 --> BRAND1 SG2 --> BRAND1 SG3 --> BRAND2 style BRAND2 fill:#d4edda style SG3 fill:#d4edda style S4 fill:#d4edda

Final Partner Account structure

After four onboard API

calls, the Partner Account now has:

2 Business Entities: One in the US, one in Germany
2 Payment Accounts: One for each legal entity
2 Brands: TechGear and GearPro
3 Store Groups: US (TechGear), EU (TechGear), US (GearPro)
4 Stores: US website, SF physical store, EU website, GearPro website

Each incremental onboard API

call added new resources without requiring the Partner to resend existing data, enabling progressive account expansion as the business grew.

Common use cases

Adding stores as Partners expand

When Partners open new locations (physical stores, websites, or mobile apps), call onboard API

with only the new Store resource. Reference the existing Store Group and Brand.

Onboarding with minimal initial data

If Partner information is incomplete during initial onboarding, create the Partner Account with minimal required data, then call onboard API

again later to add Brands, Stores, or Business Entity details as they become available.

Expanding to new markets

When Partners enter new markets requiring different legal entities, call onboard API

to add:

New Business Entity for the new market
New Payment Account linked to the new Business Entity
New Store Group for market-specific stores

Supporting multi-brand Partners

When Partners launch new brands, call onboard API

to add:

New Brand resource
New Store Group linked to the new Brand
Associate the Store Group with the appropriate Payment Account

Error handling

409 Conflict: Resource mismatch

If you include an existing resource with different field values, the request fails with a 409 Conflict error.

Example: You try to add a new Store Group but accidentally change the Brand's display_name:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "TECHGEAR001",
  "partner_account_name": "TechGear",
  "brands": [
    {
      "brand_reference": "BRAND-TECHGEAR",
      "display_name": "TechGear Electronics"  // Different from stored value
    }
  ]
}