Price Plans

After the Acquiring Partner signs a contract with Klarna and agrees on pricing, Klarna will create a Price Plan that connects the partner account to fees and Payment Products. It is a core entity and is used to manage how prices are set and updated for partners and their sub-partners.

Relationships & Dependencies

Each Price Plan is linked to a Rate Card, which stores the actual rates. Rate Cards are reusable and required for every Price Plan. A Partner Account can have multiple Price Plans, but only one is required for onboarding.

Price_Plan_Default : Price Plan Price_Plan_Version_1 : Price Plan Version 1 Price_Plan_Version_2 : Price Plan Version 2 Rate_Card_Standard_GKD : Rate Card A Rate_Card_Default : Rate Card B Price_Plan_Default --> Price_Plan_Version_1 : Active, Effective from 2024-01-01 until 2024-03-31 Price_Plan_Default --> Price_Plan_Version_2 : Inactive, Effective from 2024-04-01 Price_Plan_Version_1 --> Rate_Card_Standard_GKD Price_Plan_Version_2 --> Rate_Card_Default

Resource Properties

Price Plans

GET:/v2/distribution/products/payment/price-plans/{price_plan_id}

Show recommended

Parameter	Required	Description
`price_plan_id`	Yes	The identifier assigned to the price plan
`rates`	Yes
`rates[]`	Yes
`version`	Yes	Version number
`effective_from`	Yes	Timestamp in ISO 8601 with timezone Valid examples: 2025-06-24T05:51 2025-06-24T05:51:48Z 2025-06-24T05:51:48.1Z 2025-06-24T05:51:48.12Z 2025-06-24T05:51:48.123Z

Here you can find all required parameters for this operation readPricePlan

Lifecycle

Price Plans can have multiple versions, allowing for future-dated changes and version control. The management process includes creating the Rate Card, associating it with a Price Plan, and setting effective dates. The process is documented and managed internally, with specific steps for creation, updating, and sharing with partners. When a Price Plan has been requested and created, it can only have one state: Published.

Integration with Partner Management API

To expose and use Price Plans in transactions and for partners, Partner Management API sets its price plan id in the distribution profile.

Frequent Use Cases

Create a Price Plan for new Acquiring Partner

Pricing Team while onboarding process can request Price Plan creation.

Use Price Plan to price transaction

Every transaction will be priced by requested parameters such as Price Plan and Payment Program and others.

Get Price Plans for MoR Partner

As defined in Partner Management API.

Returns all the Price Plan for a Partner. It shows Price Plans that have been or are available to a specific Partner

Public endpoint

GET https://api-global.klarna.com/v2/distribution/products/payment/price-plans

Example response

JSON

[
    {
        "price_plan_id": "krn:partner:global:pricing:payments:price-plan:ad71bc48-8a07-4919-a2c1",
        "price_plan_name": "Klarna:Stripe:Payments:2024:Enterprise:1",
        "versions": [ 
            {
                "version": 1,
                "effective_from":"2024-01-01T00:00.00Z",
                "effective_to": "2024-06-01T23:59.59Z",
                "comment": "Currently Active"

Request parameters

Field	Type & Mandate	Requirement	Description
partner_account_id	String<Krn>	Mandatory	A Partner Account Id of type Distribution Partner.

Response

Field	Type & Mandate	Description
price_plan_id	Mandatory, String<krn>	Id of Price Plan
price_plan_name	Mandatory, String	Internal name of price Plan
versions	Mandatory, List	Versions of price plan.Each plan has minimum 1 version
versions.version	Mandatory, Long	Version number
versions.effective_from	Mandatory, DateTime in UTC	Date when version starts to be effective
versions.effective_to	Mandatory, DateTime in UTC	Date when version stops to be effective
versions.comment	Mandatory, String	Comment about version to help humans to read if it's active

Get Price Plan

As defined in Partner Management API.

What Partners will retrieve in Partner Management API. Returns the Price Plan for a Partner. It shows Price Plans that have been or are available to a Partner.

Public endpoint

GET https://api-global.klarna.com/v2/distribution/products/payment/price-plans/{price_plan_id}

Example Request

GET /{price_plan_id}?merchant_category_code={mcc-code}&date_time={date_time}&customer_country={customer_country}&partner_country={partner_country}&pricing_payment_category={pricing_payment_category}&payment_program_id={payment_program_id}

Notes:

Assumed this will be used for Partners to know the applicable price plan for a sub-partner's specific attributes. Sub-partner only need to show something specific to them: one MCC, one market, potentially subset of distribution_channels

Example response

Notes:
For customer country based price plans, the rates will have customer_country populated, whereas for partner country based price plans, the rates will have partner_country populated.

Customer country based price plan payload

JSON

{
  "price_plan_id": "krn:partner:global:pricing:payments:price-plan:ad71bc48-8a07-4919-a2c1",
  "price_plan_name": "Customer based price plan",
  "rates": [
    {
      "payment_program_id": "krn:partner:global:pricing:payment:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
      "currency": "USD",
      "customer_country": "US",
      "pricing_payment_category": "DIGITAL",
      "merchant_category_code": "5117",

Partner country based price plan payload

JSON

{
  "price_plan_id": "krn:partner:global:pricing:payments:price-plan:ad71bc48-8a07-4919-a2c1",
  "price_plan_name": "Partner basedprice plan",
  "rates": [
    {
      "program_id": "krn:partner:global:pricing:payment:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
      "program_name": "Pay Later 30",
      "currency": "USD",
      "partner_country": "US",
      "pricing_payment_category": "DIGITAL",

Example Error Response:

JSON

{
  "error_id": "d78f526a-49bb-4095-9256-10a4c365b726",
  "error_type": "INPUT_ERROR",
  "error_code": "VALIDATION_ERROR",
  "error_message": "Validation error."
}

Example Validation ErrorResponse:

JSON

{
  "error_id": "d78f526a-49bb-4095-9256-10a4c365b726",
  "error_type": "INPUT_ERROR",
  "error_code": "VALIDATION_ERROR",
  "error_message": "Validation error.",
  "validation_errors": [
    {
      "parameter": "version",
      "reason": "must be greater than or equal to 0"
    }

Request parameters

Field	Type & Mandate	Request Type	Requirement	Description
partner_account_id	String<Krn>	Param	Mandatory	A Partner Account Id of type Distribution Partner.
merchant_category_code	String	Query	Optional	A Merchant Category Code. Eg: 0017, 5151Valid MCC (ref). Pricing Engine should define what MCC we support
date_time	Date time in UTC	Query	Optional	If not provided - defaults to now
customer_country	Enum, Country Code	Query	Optional	US, SE
partner_country	Enum, Country Code	Query	Optional	US, SE
pricing_payment_category	Enum	Query	Optional	DIGITAL, PHYSICAL
version	Number	Query	Optional	Price planversion.
size	String	Query	Optional	Pagination option, for the size of rates list in one page.
starting_after	String	Query	Optional	A cursor used in pagination, referring to a specific item. The `last_item` returned from a previous call can be used here. The next page will list items after this item. Cannot be used together with `ending_before`. If both starting_after and ending_before are omitted, the first page will be returned.
ending_before				A cursor used in pagination, referring to a specific item. The `first_item` returned from a previous call can be used here. The next page will list items up until, but not including, this item. Cannot be used together with `starting_after`. If both starting_after and ending_before are omitted, the first page will be returned.

Response

Field	Type & Mandate	Description
price_plan_id	Mandatory, String<krn>	Id of Price Plan
price_plan_name	Mandatory, String	Name of Price Plan
rates	Mandatory, List	List of rates for supplied mcc effective on supplied date
rates[x]. program_id	Mandatory, String	Id of program. Program is a grouping of payment methods.
rates[x].program_name	Mandatory, String	Name of program. Program is a grouping of payment methods.
rates[x].currency	Mandatory, String	Currency for rate
rates[x].customer_country	Optional, String
rates[x].partner_country	Optional, String
rates[x].pricing_payment_category	Mandatory, String
rates[x]. merchant_category_code	Mandatory, String
rates[x].rate.fixed_fee.amount	Optional, Long	Value of fixed fee multiplied by 100. Eg: 20$ is fixed: 2000Same rules as order_amount in payments V2 API. fixed_fee might not be present for the cross border fee, buy rate incentives like volume discount.
rates[x].rate.fixed_fee.currency	Mandatory, String	ISO currency code of the fee. Eg: USD for $. fixed_fee might not be present for the cross border fee, buy rate incentives like volume discount.
rate[x].rate.variable_fee.percentage	Mandatory, Long	Percentage points representing percent value multiplied by 100. Eg: 1.5% is 150.
rate[x].price_cap.name	Mandatory, String	Type of price cap applied. Eg. MICRO_TRANSACTION_CAP
rate[x].price_cap.percentage	Mandatory, Long	Percentage of price cap applied multiplied by 100. Eg. 1.5% is 150
rate[x].currency	Optional, String	Currency for applicable fixed fee. Eg: "usd", "sek" etc
version	Mandatory, String	Number with Price Plan version
effective_from	Mandatory, Date time in UTC	Date time when price plan version is getting effective from.
effective_to	Optional, Date time in UTC	Date time when price plan version stops getting effective.
comment	String	A comment with more readable information about if price plan version is active.
pagination	Object	Common pagination object with pagination information. See example for full expansion.

Error Codes

Error Code	Internal Error Code	Description
VALIDATION_ERROR	VALIDATION_ERROR	One or many validation errors. Details are described in `validation_errors` .
RESOURCE_NOT_FOUND	PRICE_PLAN_NOT_FOUND	If price plan id cannot be found
RESOURCE_NOT_FOUND	PRICE_VERSION_PLAN_NOT_FOUND	if version of a price plan cannot be found

API Operations

listPricePlans * readPricePlan