On-site messaging API reference

Make sure you are calling the right endpoint per environment and region, the following query parameters are allowed:

Along with the query params you need to pass request headers to the API. If you are calling the API from your frontend, this will be handled automatically.

The API will also return response headers, for debugging and caching purposes.

Depending on your request the API will return the relevant status code

The OSM team will try to prevent making breaking changes to the API as much as possible, but in the case this is not possible, we will create a new version of the API endpoint and communicate with the integrator as soon as possible so they can update to the latest version.

The following changes are considered as "non-breaking":

• Addition of optional or read-only fields/properties
• Re-ordering of fields in the JSON response
• Re-ordering or addition of nodes in the JSON response nodes array
• Addition of HTTP headers
• Addition of new values to an enum if there is a default defined
• Addition of new HTTP methods to existing resources

We recommend integrators make the HTTP call in an asynchronous way and set a sensible HTTP client timeout when calling the OSM API. We suggest that the HTTP client timeout be set to at least 5 seconds. This will prevent the user experience on your application to be degraded if the OSM API is not reachable or not responding for any reason.

Placement Types containers of messages returned by OSM.

The backend API implementation of OSM currently supports these two types of placements:

• credit-promotion-badge
• top-strip-promotion-badge

credit-promotion-badge

These are amount-based placements that will deliver messaging with an offering for the specific purchase_amount provided, where available. The placements can be used in various places across the website, such as cart view, product details page, product list page, etc

{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Make 4 payments of $128.67. No fees."
     },
     {
       "type": "ACTION",

top-strip-promotion-badge

These are non amount-based placements that are designed to show messaging on landing pages.

{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Make 4 payments of $128.67. No fees."
     },
     {
       "type": "ACTION",

Once you get the response from the OSM API endpoint you can render the ad in your application using the content object present in the response.

Content object schema

For easier integration, we defined an Ad as a collection of nodes.  These nodes contain the text, actions (or links) elements of the ad, and the image/s needed to render the Ad. 

OSM supports 3 types of nodes:

Text node

The lines of text for the ad. The number of text elements will change depending on the placement group requested.

{
  "type": "TEXT",
  "name": "TEXT_MAIN",
  "value": "Buy now, pay later"
 }

Action node

The possible call-to-action buttons or links contained in the ad. These elements will contain a URL that should be opened when the user clicks on the button/link.

We currently support 2 types of action nodes:

• ACTION_LEARN_MORE: Link to a external page hosted on Klarna servers that displays more information to the customer about the advertised payment method
• ACTION_PREQUALIFY: Link to an external page hosted on Klarna servers that allows the customer to perform a pre-qualify credit check. Note: This only applies if the merchant supports financing with Klarna.

{
  "type": "ACTION",
  "name": "ACTION_LEARN_MORE",
  "label": "Learn more",
  "url": "https://na-assets.klarnaservices.com/learn-more/index.html?..."
}

{
  "type": "ACTION",
  "name": "ACTION_PREQUALIFY",
  "label": "See if you're prequalified",
  "url": "https://na-assets.klarnaservices.com/eligibility/index.html?..."
}

Image node

• URL of the image needed to display the OSM ad. 
• Alternative text is also provided for accessibility reasons.

{
  "type": "IMAGE",
  "name": "KLARNA_BADGE"
  "alt": "Klarna",
  "url": 'http://us-assets.klarnaservices.com/images/badges/klarna.svg'
}

List of available nodes by type of placement

Each type of placement will have a different representation in nodes. For example: top-strip placements don’t have a TEXT_LEGAL node. Here is a list of all the possible nodes that can be returned per placement.

credit-promotion-badge

top-strip-promotion-badge

Branding images

The API returns svg images, if you want to use a different image type, please see below