Klarna Agentic product protocol

The Agentic product protocol API is a standardized data interface built on Klarna’s production catalog. Access to the Agentic Product Protocol API is available for approved partners and developers, please reach out to agenticproductprotocol@klarna.com for access.

15 min read

How to get started

You can explore the API here:

EU Swagger: https://api.pricerunner.com/docs/?urls.primaryName=Agentic+Product+API
US Swagger: https://api-us.pricerunner.com/docs/?urls.primaryName=Agentic+Product+API

These Swagger environments allow you to review endpoints, test queries, and understand the data model before starting an integration.

To request access to our API, please reach out to agenticproductprotocol@klarna.com.

We're continuously evolving this API together with our partners to ensure it meets real-world needs and supports your agentic and product discovery use cases.

What the Klarna Agentic Product Protocol API does

The Agentic Product Protocol API exposes searchable products (unique items like "Apple iPhone 17 Pro, 512GB Silver") and merchant offers attached to those products (price, stock, shipping, payment methods, etc.). Agents and apps can:

1.
search products by free text (semantic search in v2); and
2.
fetch rich product details + current offers for any set of product IDs. It's production-ready in the US and EU, backed by Klarna's normalized catalog and unified taxonomy so results are comparable across merchants.

Data Model & Terminology

The Agentic Product Protocol API is built around two core entities — Products and Offers — which together describe what is being sold and under what conditions. Understanding this distinction is key to using the API effectively.

Term	Description
Product	A unique item in Klarna's catalog, defined by attributes such as brand, model, and specifications. Example: Apple iPhone 17 Pro, 256GB Silver. Products act as a single reference point that links all merchant listings for that item.
Offer	A merchant's listing of a specific product. Offers include pricing, stock status, shipping costs, delivery times, and supported payment methods. Multiple offers can exist for the same product, each from a different merchant.

Example relationship:

A search for "Apple iPhone 17 Pro" may return a single Product object.

When you request offers for that product, the API returns multiple Offers, such as:

Apple Store – $1,599 (In Stock)
Best Buy – $1,579 (Preorder)

In short:

Products describe what the item is.
Offers describe where and how it's available for purchase.

Environments & Markets

Regions deployed

EU: AT, DE, DK, ES, FI, FR, IE, IT, NL, NO, SE, UK
US: US

The markets listed above are those currently available through the Agentic Product Protocol API.

Base URLs

Region	Base URL
EU	`https://api.pricerunner.com`
US	`https://api-us.pricerunner.com`

All endpoint paths documented below are appended to the base URL for the region you are integrating with.

Notes

Market path parameter uses ISO 3166-1 alpha-2 codes. We recommend uppercase; the value is normalised, so lowercase is also accepted.
Use UK for the United Kingdom market.
Currencies are the local market currency (e.g., USD for US, EUR for many EU markets, SEK for SE, etc.).

Versioning & Stability

Base path includes version: /agentic/v1/... or /agentic/v2/...
Product Search is available at v2 (current) and v1 (deprecated). Product Listings remains at v1.
We aim for backward-compatible changes in minor updates.
Breaking changes ship with a new major version path.

Core Endpoints

Endpoint	Description
Product Search (v2)	The current Product Search endpoint (`/agentic/v2/product/search/{market}`) uses semantic search to find products across merchants by free-text query. Returns normalized product data — including images and brands — ready for search, comparison, or AI reasoning. The v1 search endpoint is deprecated.
Product Listings	The Product Listings endpoint (`/agentic/v1/product/offers/{market}`) returns detailed information for a specific product and its offers from verified merchants. It includes prices, stock status, and shipping, all linked to a single product KRN. This enables instant offer comparison and accurate retrieval for features like recommendations, price tracking, or "save for later."

All responses are returned in JSON and include product-level and offer-level identifiers for easy mapping.

How to Retrieve Offers

This section walks through how to retrieve merchant offers for a specific product using the two main endpoints:

1.
Product Search – Find the product and get its productIdentifier.
2.
Product Listings (Offers) – Use that identifier to request detailed product and offer data.

Example: Apple iPhone 16e, 128GB, Apple Intelligence

Let's say you want to display all available merchant offers for the Apple iPhone 16e, 128GB, Apple Intelligence.

Step 1 — Search for the product

Use the Product Search endpoint to find the product and retrieve its Klarna productIdentifier.
Copy the productIdentifier from the response.

Step 2 — Retrieve offers for that product

Now, use the Product Listings endpoint to request all merchant offers for that product identifier. Offers will contain information such as SKU, price, stock status, shipping and more.
This response lists multiple offers for the same product.

You can include multiple product identifiers (comma-separated) in a single offers request to retrieve offers in bulk for several products at once.

Product Search Endpoint

Use this endpoint to search for products by free-text query, such as "iphone 17 silver" or "wireless headphones."

Results return a list of unique products (not individual merchant offers) that match your query, along with basic product information such as name, image, brand, and category.

Request

GET /agentic/v2/product/search/{market}

Path Parameters

Parameter	Required	Description
`market`	✅	EU: AT, DE, DK, ES, FI, FR, IE, IT, NL, NO, SE, UK. US: US

Query Parameters

Parameter	Required	Description
`offset`		Used for pagination. The number of products to skip before returning results (e.g., `offset=10` retrieves the next "page" of products). Minimum: 0.
`q`	✅	The free-text search term used to find products. Keep queries to 100 characters or fewer; longer queries are not rejected, but fall outside the supported range and may degrade result quality. Example: `iphone 17 silver`.
`size`		Number of products to include in the response. Minimum: 1. Maximum: 100. If omitted, the search backend's own default applies (currently 10).

Headers

Header	Required	Description
`tokenId`	✅	Access token provided during onboarding. Used for authentication.

Example requests

US:

BASH

1 2

curl -H "tokenId: YOUR_TOKEN" \
  "https://api-us.pricerunner.com/agentic/v2/product/search/US?offset=0&q=silver%20iphone%2017&size=10"

EU (Sweden):

BASH

1 2

curl -H "tokenId: YOUR_TOKEN" \
  "https://api.pricerunner.com/agentic/v2/product/search/SE?offset=0&q=silver%20iphone%2017&size=10"

These requests search for "silver iphone 17", return up to 10 products starting from offset 0, and authenticate with the tokenId header.

V1 (deprecated)

DEPRECATED: Use /agentic/v2/product/search/{market} instead. The v1 endpoint will be removed in a future major version.

GET /agentic/v1/product/search/{market}

Uses the same query parameter names as v2 (offset, q, size); bounds such as the maximum size may differ from v2—confirm in Swagger for the v1 search operation. v1 also supports:

Parameter	Required	Description
`sortOrders`		Comma-separated list of sorting methods. If omitted, no explicit sort is requested and the search backend's default ordering applies. Available options: `POPULARITY` (current user engagement), `NAME` (alphabetical order by product name), `RATING` (user review ratings), `TREND` (trending products over the past week), `HOT` (weighted combination of popularity, trend, and sales). An unrecognised value returns 400 Bad Request.

Example v1 request:

BASH

1 2

curl -H "tokenId: YOUR_TOKEN" \
  "https://api-us.pricerunner.com/agentic/v1/product/search/US?offset=0&q=silver%20iphone%2017&size=10&sortOrders=TREND"

The response shape is identical to v2.

Response

When the request is successful, the API returns a list of products matching your search query. Each product represents a unique item (for example, Apple iPhone 17 Pro Max, 1TB Silver), not an individual merchant offer.

Response Fields

Field	Type	Description
`totalNumberOfHits`	Long	Total number of search hits in the given market, as reported by the search backend. Large result sets are capped upstream. Use with `offset` and `size` for pagination. The `products` array may contain fewer items than `size`, or be empty, when hits are filtered out by product classification.
`products`	Array	A list of product objects, each representing a unique item in Klarna's product catalog.

Each product object contains the following fields:

Field	Type	Description
`productIdentifier`	String	Klarna's unique product ID. Use this ID with the Product Listings endpoint to retrieve offers for this item.
`name`	String	The product's display name, as listed in Klarna's catalog.
`klarnaProductPageUrl`	String (URL)	Link to Klarna's shopping page for the product, where users can see all merchant offers.
`imageUrl`	String (URL)	A representative image of the product. May be `null` for products without a main image.
`brand`	Object	Contains brand details when available: `name` — Brand name; `logoUrl` — Brand logo (nullable). May be `null` if brand information is unavailable.
`categoryName`	String	The product's main category in Klarna's unified taxonomy. Optional in the response schema, so handle a missing value defensively.
`subcategoryName`	String	A more specific subcategory, where available. May be `null` for products that don't belong to a subcategory.

Example response (excerpt)

JSON

1 2 3 4 5 6 7 8 9 10

{
  "totalNumberOfHits": 12,
  "products": [
    {
      "productIdentifier": "krn:kpdc:product:3431242055",
      "name": "Apple iPhone 17 Pro Max, 1TB Silver",
      "klarnaProductPageUrl": "https://www.klarna.com/us/shopping/pl/cl1/3431242055/Mobile-Phones/Apple-iPhone-17-Pro-Max-1TB-Silver/",
      "imageUrl": "https://owp.klarna.com/product/640x640/3239078895/Apple-iPhone-17-Pro-Max-1TB-Silver.jpg",
      "brand": {
        "name": "Apple",

Product Listings

Use this endpoint to retrieve detailed product information and merchant offers for specific product identifiers returned by the Product Search endpoint. The REST path is /agentic/v1/product/offers/{market} (the offers segment, not listings).

Each product returned includes:

Enriched product details (e.g., description, rating, GTINs, and rank within category)
All available merchant offers, including price, stock status, shipping cost, delivery times, and payment options

This endpoint is typically used when a user has selected or shown interest in a specific product and you want to display merchants offering that item.

Request

GET /agentic/v1/product/offers/{market}

Path Parameters

Parameter	Required	Description
`market`	✅	EU: AT, DE, DK, ES, FI, FR, IE, IT, NL, NO, SE, UK. US: US

Query Parameters

Parameter	Required	Description
`itemConditionFilters`		Comma-separated list of condition filters. Accepted values: `NEW` (brand-new product), `REFURBISHED` (professionally restored item), `USED` (previously owned product), `UNKNOWN` (condition not specified by the merchant).
`maxPrice`		Maximum price filter in the market's local currency (integer). Example: `maxPrice=500`.
`minPrice`		Minimum price filter in the market's local currency (integer). Example: `minPrice=100`.
`productIdentifiers`	✅	Comma-separated list of product identifiers returned from the Product Search endpoint. Maximum 50 identifiers per request; requests with more than 50 return 400 Bad Request. Example: `krn:kpdc:product:3431242055,krn:kpdc:product:3431242200`.

Headers

Header	Required	Description
`tokenId`	✅	Access token provided during onboarding. Used for authentication.

Example requests

US:

BASH

1 2

curl -H "tokenId: YOUR_TOKEN" \
  "https://api-us.pricerunner.com/agentic/v1/product/offers/US?itemConditionFilters=NEW%2CUNKNOWN&productIdentifiers=krn%3Akpdc%3Aproduct%3A3431242055%2Ckrn%3Akpdc%3Aproduct%3A3431242200"

EU (Sweden):

BASH

1 2

curl -H "tokenId: YOUR_TOKEN" \
  "https://api.pricerunner.com/agentic/v1/product/offers/SE?itemConditionFilters=NEW%2CUNKNOWN&productIdentifiers=krn%3Akpdc%3Aproduct%3A3431242055%2Ckrn%3Akpdc%3Aproduct%3A3431242200"

These requests retrieve product details and merchant offers for two product identifiers, filtered to include only NEW or UNKNOWN condition offers, and authenticate with the tokenId header.

Response

The response contains a list of product listings, each including:

1.
A product object with enriched product details.
2.
A list of offers from merchants currently selling that product.

Response Fields

Field	Type	Description
`productListings`	Array	Each entry pairs a `product` object with an `offers` array of merchant listings (price, stock, shipping, and related fields) for that product.

Product Fields

Field	Type	Description
`productIdentifier`	String	Klarna's unique product ID.
`name`	String	The full product name as listed in Klarna's catalog.
`categoryName`	String	Product's main category in Klarna's taxonomy.
`subcategoryName`	String	More specific subcategory; may be `null`.
`brand`	Object	Contains brand details: `name` – Brand name; `logoUrl` – URL to the brand logo (nullable). The whole `brand` object may be `null` when the product has no associated brand.
`klarnaProductPageUrl`	String (URL)	Klarna shopping page where the product and its offers are displayed.
`imageUrl`	String (URL)	Product image URL. May be `null` for products without a main image.
`gtin14s`	Array of Strings	GTIN-14 identifiers associated with this product. Empty array when none are known.
`rating`	String	Average user rating, typically formatted as `"X.Y"`. May be `null`.
`numberOfRatings`	Integer	Number of user reviews associated with the product. `0` when the product has no ratings.
`rank`	Long	Product's popularity rank within its category. May be `null`.
`description`	String	Product description text. May be `null`.
`attributes`	Array of Objects	Structured product attributes. Each attribute has `name` (attribute name, e.g., `"Screen Size (\")"`) and `values` (array of one or more string values, e.g., `["6.9"]`). Empty array when the product has no attributes.

Offer Fields

Field	Type	Description
`offerName`	String	Merchant-specific name of the product offer.
`merchant`	Object	Merchant information: `merchantName` (display name of the merchant), `merchantLogoUrl` (logo URL, nullable), `merchantProductSku` (SKU assigned by the merchant), `international` (`true` if the offer is cross-border, sold from a different market).
`offerUrl`	String (URL)	Klarna-affiliated link to the merchant's product page. Always present.
`price`	Object	Product price: `value` (price as a string), `currency` (ISO currency code).
`shippingCost`	Object	Shipping cost: `value` (cost as a string), `currency` (ISO currency code). May be `null`.
`stockStatus`	Enum	Product availability. Possible values: `IN_STOCK`, `OUT_OF_STOCK`, `PREORDER`, `SPECIAL_ORDER`, `BACKORDER`, `COLLECT_IN_STORE`, `UNKNOWN`.
`deliveryTime`	Object	Estimated delivery window: `minDays` (minimum estimated delivery time, nullable), `maxDays` (maximum estimated delivery time, nullable).
`paymentMethods`	Array	Supported payment options, each containing `name` and `imageUrl` (`imageUrl` is nullable).
`gtin14`	String	GTIN-14 associated with the specific offer (nullable).
`attributes`	Array of Objects	Offer-specific structured attributes. Same shape as product `attributes`: `name` and `values`. May be empty.

Example response (excerpt)

JSON

1 2 3 4 5 6 7 8 9 10

{
  "productListings": [
    {
      "product": {
        "productIdentifier": "krn:kpdc:product:3431242055",
        "name": "Apple iPhone 17 Pro Max, 1TB Silver",
        "categoryName": "Mobile Phones",
        "subcategoryName": null,
        "brand": {
          "name": "Apple",

Standard Response Codes

Product Search Endpoint

Code	Meaning	Description
200 OK	Success	The response body contains the search result.
400 Bad Request	Invalid request	One or more parameters are missing or malformed (for example, missing `q`, an invalid query value, or a market code that is not supported by the region you are calling).
403 Forbidden	Unauthorized token	The `tokenId` header is missing, invalid, or not accepted for this region.
429 Too Many Requests	Rate limit exceeded	Too many requests sent in a short time for this token.
500 Internal Server Error	Upstream or processing error	An upstream service was unavailable or returned an unexpected response. Retry with exponential backoff.

Product Listings Endpoint

Code	Meaning	Description
200 OK	Success	The response body contains the product listings and offers.
400 Bad Request	Invalid request	One or more parameters are missing or malformed (for example, missing `productIdentifiers`, more than 50 identifiers, or an unsupported market code).
403 Forbidden	Unauthorized token	The `tokenId` header is missing, invalid, or not accepted for this region.
429 Too Many Requests	Rate limit exceeded	Too many requests sent in a short time for this token.
500 Internal Server Error	Upstream or processing error	An upstream service was unavailable or returned an unexpected response. Retry with exponential backoff.

Error Handling Best Practices

When your client application receives an error response:

400 — Check required query parameters and path values (q, productIdentifiers, market code, etc.) and ensure they match the expected format. Confirm the market code is supported by the region you are calling.
403 — Send a valid tokenId header and confirm it is authorised for the region and operation you are calling.
429 — Implement exponential backoff or a short retry delay before resending the request.
500 — An upstream service was unavailable or returned an unexpected response; retry with exponential backoff. Upstream unavailability surfaces as 500 rather than 503, so treat a 500 as potentially transient.