Custom Notifications

Norce Checkout Path

This guide covers the Norce Checkout path, where the Norce Checkout Order API and adapter APIs handle checkout and payment. The legacy checkout path using the Commerce Services Shopping Service is documented separately in Working with the Checkout Process. Do not mix Shopping Service checkout operations into the Norce Checkout flow after the basket is created.

In this guide, we'll look at adding a custom notification to our checkout. We'll explore how to receive a notification when an order is completed in our channel.

Configure default notification

So far every time we've used a configuration it has belonged to an adapter. This time we're creating a configuration without any adapter, simply to inform Norce Checkout that we wish to include this notification in any order created in our channel.

Set configuration

PUT /api/v1/configuration/merchants/{merchant}/channels/{channel}/configurations/static_notifications
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer super-secret-and-valid-token
Host: {slug}.api-se.playground.norce.tech/checkout/configuration
Content-Type: application/json

{
  "$schema": "https://{slug}.api-se.playground.norce.tech/checkout/configuration/openapi/v1/schemas/configuration.json",
  "id": "static_notifications",
  "active": true,
  "order": {
    "notifications": [
      {
        "description": "Notify on order completed.",
        "reference": "27565c74-96c5-4e8a-a200-f9e7b8b5a9bd",
        "scope": "/state/currentStatus",
        "schema": {
          "enum": [
            "completed"
          ]
        },
        "invoke": "https://httpstat.us/204"
      }
    ]
  }
}

Preparing a Basket in Norce Commerce

Create a basket
Insert a basket item
Set payment method to 239
Set delivery method to 128 (if you're using KSA)

Creating an Order in Norce Checkout

Create an order by providing the basket ID, culture, and currency.

Create order

POST /api/v1/orders
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer {token}
Host: {slug}.api-se.playground.norce.tech/checkout/norce-adapter
Content-Type: application/json

{
  "cartReference": {basketId},
  "culture": "sv-SE",
  "currency": "SEK"
}

201 Created
Content-Type: application/json

{
  "id": "{orderId}"
}

Inspect our order

If we get our order now we'll find that it has been created with our static notification in place!

Get order

GET /api/v0/checkout/orders/{orderId}
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer {token}
Host: {slug}.api-se.playground.norce.tech/checkout/order

200 OK
Content-Type: application/json

{
  ...
  "notifications": [
    ...,
    {
      "id": "onDxQKmyPXxgjUffufbWAYygaEnb",
      "description": "Notify on order completed.",
      "scope": "/state/currentStatus",
      "schema": {
        "enum": [
          "completed"
        ]
      },
      "invoke": "https://httpstat.us/204"
    }
  ],
  ...
}

Create a Klarna Checkout payment

When we create a payment using the Klarna adapter the only context we need to provide is the orderId.

Create payment

POST /api/checkout/v1/orders/{orderId}/payments
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer {token}
Host: {slug}.api-se.playground.norce.tech/checkout/klarna-adapter

200 OK
Content-Type: application/json

{
  "id": "{paymentId}",
  "status": "checkout_incomplete",
  "htmlSnippet": "<div id=\"klarna-checkout-container\" style=\"overflow: hidden;\">\n  <div id=\"klarna-unsupported-page\">\n  <style type=\"text/css\">\n  @-webkit-keyframes klarnaFadeIn{from{opacity:0}to{opacity:1}}@-moz-keyframes klarnaFadeIn{from{opacity:0}to{opacity:1}}@keyframes klarnaFadeIn{from{opacity:0}to{opacity:1}}#klarna-unsupported-page{opacity:0;opacity:1\\9;-webkit-animation:klarnaFadeIn ease-in 1;-moz-animation:klarnaFadeIn ease-in 1;animation:klarnaFadeIn ease-in 1;-webkit-animation-fill-mode:forwards;-moz-animation-fill-mode:forwards;animation-fill-mode:forwards;-webkit-animation-duration:.1s;-moz-animation-duration:.1s;animation-duration:.1s;-webkit-animation-delay:5s;-moz-animation-delay:5s;animation-delay:5s;text-align:center;padding-top:64px}#klarna-unsupported-page .heading{font-family: \"Klarna Headline\", Helvetica, Arial, sans-serif;color: rgb(23, 23, 23);font-size: 36px;letter-spacing: -0.2px;-webkit-font-smoothing: antialiased;}#klarna-unsupported-page .subheading{font-family: \"Klarna Text\", \"Klarna Sans\", Helvetica, Arial, sans-serif;color: rgb(23, 23, 23);-webkit-font-smoothing: antialiased;line-height: 28px;font-weight: 400;font-size: 19px;max-width: 640px;margin: 20px auto;}#klarna-unsupported-page .reload {cursor: pointer;outline: none;-webkit-tap-highlight-color: rgba(255, 255, 255, 0);border-width: 1px;background-color: rgb(38, 37, 37);border-color: rgb(38, 37, 37);padding: 15px 24px;margin-top: 15px;color: rgb(255, 255, 255);font-family: \"Klarna Text\", \"Klarna Sans\", Helvetica, Arial, sans-serif;font-weight: 500;text-rendering: geometricprecision;font-size: 100%;}\n  </style>\n  <h1 class=\"heading\">Something went wrong</h1>\n  <p class=\"subheading\">Sorry for any inconvenience, please try reloading the checkout page or try again later.</p>\n  <p class=\"subheading\">If the problem persists it maybe be because you are using an old version of the web browser which is not safe nor compatible with modern web sites. For a smoother checkout experience, please install a newer browser.</p>\n  <button class=\"reload\" onclick=\"reloadCheckoutHandler && reloadCheckoutHandler()\">Reload checkout</button>\n  </div>\n  <script id=\"klarna-checkout-context\" type=\"text/javascript\">\n  /* <![CDATA[ */\n  var reloadCheckoutHandler;\n  (function(w,k,i,d,n,c,l){\n    w[k]=w[k]||function(){(w[k].q=w[k].q||[]).push(arguments)};\n    l=w[k].config={\n      container:w.document.getElementById(i),\n      ORDER_URL:'https://js.playground.klarna.com/eu/kco/checkout/orders/{klarnaOrderId}',\n      AUTH_HEADER:'KlarnaCheckout excm1q49fqsanz7q83ny',\n      IS_CANARY:false,\n      IS_IN_CLIENT_ROLLOUT:false,\n      LOCALE:'{culture}',\n      ORDER_STATUS:'checkout_incomplete',\n      MERCHANT_NAME:'{yourKlarnaMerchantName}',\n      GUI_OPTIONS:[],\n      ALLOW_SEPARATE_SHIPPING_ADDRESS:false,\n      PURCHASE_COUNTRY:'{purchaseCountry}',\n      PURCHASE_CURRENCY:'{purchaseCurrency}',\n      TESTDRIVE:true,\n      BOOTSTRAP_SRC:'https://js.playground.klarna.com/kcoc/240913-60eb5ae/checkout.bootstrap.js',\n      FE_EVENTS_DISABLED:'false',      CLIENT_EVENT_HOST:'https://eu.playground.klarnaevt.com'\n    };\n    n=d.createElement('script');\n    c=d.getElementById(i);\n    n.async=!0;\n    n.src=l.BOOTSTRAP_SRC;\n    c.appendChild(n);\n    try{\n      ((w.Image && (new w.Image))||(d.createElement && d.createElement('img'))||{}).src =\n        l.CLIENT_EVENT_HOST + '/v1/checkout/snippet/load' +\n        '?sid=' + l.ORDER_URL.split('/').slice(-1) +\n        '&order_status=' + w.encodeURIComponent(l.ORDER_STATUS) +\n        '&timestamp=' + (new Date).getTime();\n    }catch(e){}\n    reloadCheckoutHandler = function () {\n        try{\n            ((w.Image && (new w.Image))||(d.createElement && d.createElement('img'))||{}).src =\n            l.CLIENT_EVENT_HOST+'/v1/checkout/snippet/reload?sid='+l.ORDER_URL.split('/').slice(-1)+\n            '&order_status='+w.encodeURIComponent(l.ORDER_STATUS)+'&timestamp='+(new Date()).getTime();\n            window.location.reload();\n        }catch(e){}\n    }\n  })(this,'_klarnaCheckout','klarna-checkout-container',document);\n  /* ]]> */\n  </script>\n  <noscript>\nPlease <a href=\"http://enable-javascript.com\">enable JavaScript</a>.\n  </noscript>\n</div>"
}

Complete the payment

Render snippet (see previous tutorial.)
Provide customer information.
Choose shipping option (if applicable for your setup.)
Click buy and complete the purchase.

Notification

We can now get all notifications for our order and see that a notification has been sent once the order was completed.

GET /api/v1/events?orderId={orderId}
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer {token}
Host: {slug}.api-se.playground.norce.tech/checkout/notification

Next Steps

In this tutorial, we explored how to add a custom notification to our checkout process. We configured a static notification without an adapter, ensuring it triggers when an order is completed in our channel. By setting up and inspecting the order, we confirmed that the notification works as intended. Finally, we observed how the notification is sent after completing the payment, providing valuable event updates for the order.

Next you can read up about core and explore the APIs on your own.