Partner Stores and Brands
Partner Stores and Brands defines how Acquiring Partners manage and declare the Partner stores, brands, and store groups to ensure accurate and consistent brand representation across Klarna's platforms.
Overview
Use Partner Stores, Brands, and Store groups to describe where customers can shop with Klarna and how Klarna should present a Partner’s identity to customers. This resource explains how Acquiring Partners declare and manage these entities during onboarding and throughout the Partner lifecycle to maintain accurate references and consistent brand presentation.
Each Partner Account must include at least one store. Brands and Store groups allow Klarna to accurately represent Partners’ business identities across web, app, and in-store experiences.
Relationships and dependencies
graph
PA(Partner Account)
SG(Store group)
B(Brand)
S(Store)
PA -->|1..n| SG
SG -->|1..n| S
SG -->|1..1| B
class SG primaryEntity
- Store: Describes where Klarna payment services are available to customers (for example, website, mobile app, or physical store).
- Brand: Defines the customer-facing identity (logos, display names) of a Partner’s offering.
- Store group: Connects one or more stores to a specific brand and defines shared customer-facing attributes (branding, support, and social links).
A Partner Account can include multiple store groups. Each store group is linked to exactly one brand and one or more stores. Acquiring Partners must keep these relationships up to date so Klarna can display the correct brand and store information to customers.
Resource properties
Stores
Stores define where customers interact with Klarna’s payment services via a Partner.
Each store must include a unique store_reference provided by the Acquiring Partner. This reference lets Klarna correctly associate payments and fraud checks with the right store identity.
| Type | Definition |
|---|---|
| Website | Online store where Klarna’s payment products are shown. |
| Physical store | Brick-and-mortar location where a customer can use Klarna to pay for goods. |
| Mobile app | Mobile app where Klarna’s payment options can be used. |
When declaring stores, Acquiring Partners typically provide:
- type: Store channel type. For example,
WEBSITE,PHYSICAL_STORE, orMOBILE_APP. - store_reference: Unique identifier for the store, assigned by the Acquiring Partner.
- Channel-specific details, such as:
urlfor web stores.addressfor physical stores.platformandbundle_namesfor mobile apps.
Sample request — stores submitted during onboarding
JSON
1
2
3
4
5
6
7
8
9
10
{
"stores": [
{
"type": "WEBSITE",
"store_reference": "web131231",
"url": "https://example.com/store"
},
{
"type": "PHYSICAL_STORE",
"store_reference": "store1234",Acquiring Partners can read and update store details through the following endpoints:
Brands
A brand is defined by a display name and associated visual assets that represent the Partner to customers.
Each brand must include a unique brand_reference provided by the Acquiring Partner. This reference links brands to their corresponding store groups.
Typical brand attributes include:
- brand_reference: Identifier assigned by the Acquiring Partner, used to associate a declared store group with a brand.
- display_name: Brand name displayed to customers in Klarna’s shopping experience.
- element: Object that may include:
logo_urlicon_urlfeature_image_url
Sample request — brands submitted during onboarding
JSON
1
2
3
4
5
6
7
8
9
10
{
"brands": [
{
"brand_reference": "partner_brand_01",
"display_name": "Cool Brand",
"element": {
"logo_url": "https://example.com/logo.png",
"icon_url": "https://example.com/icon.png",
"feature_image_url": "https://example.com/feature_image.png"
}At a minimum, Acquiring Partners must submit the following parameters when setting brand details during onboarding:
- display_name: Partner brand name displayed to customers in Klarna’s shopping experience.
- brand_reference: Identifier assigned by the Acquiring Partner, used to associate a declared store group with the brand.
Acquiring Partners can read and update brand details through the following endpoints:
Store groups
Store groups unify a Partner’s brand identity across multiple stores. Each store group must include a brand reference and contain one or more stores.
Acquiring Partners must submit at least one store group with the following parameters when onboarding their Partners:
- store_group_reference: Unique reference assigned by the Acquiring Partner.
- stores: One or more stores belonging to the group.
- brand_reference: Links the store group to the appropriate brand.
Store groups can also carry shared customer-facing details that apply to all stores in the group, such as support contact information and social media links.
Sample request — store_groups submitted during onboarding
JSON
1
2
3
4
5
6
7
8
9
10
{
"store_groups": [
{
"store_group_reference": "STORE_NY004",
"brand_reference": "brand_002",
"stores": [
{
"type": "WEBSITE",
"store_reference": "web131231",
"url": "https://example.com/store"Acquiring Partners can read and update store groups through the following endpoints:
Lifecycle
stateDiagram-v2
direction LR
Onboarding --> Activation:::box2
Activation --> Update:::box3
Update --> Maintenance:::box4
- Onboarding: The Acquiring Partner defines stores, brands, and store groups for each Partner and submits them via the Management API.
- Activation: Klarna validates the submitted data and associates store groups with their corresponding brands and stores.
- Update: The Acquiring Partner updates store, brand, or store group attributes via the Management API as the Partner’s setup changes.
- Maintenance: If data is incomplete or invalid, Klarna triggers webhooks. The Partner must correct and resubmit the affected resources.
Example use cases
- An Acquiring Partner onboards a retailer with both online and physical stores under one brand.
- A Partner adds a new mobile app channel and links it to an existing store group.
- A Partner updates their brand logo and pushes the update to Klarna via the Management API.
Related articles