Norce adapter

An adapter for the Norce Commerce platform allowing you to create a Norce Checkout order from a Norce Commerce basket. Making it easy to add a payment and complete your checkout in Norce Checkout, all while keeping Norce Commerce synced and seeing the order available in Norce Commerce afterwards.

Configuration

The configuration schema for this adapter can be found at the following url.

Copy

Copied

https://<slug>.api-se.<environment>.norce.tech/checkout/norce-adapter/openapi/v1/schemas/norce_adapter.json

Example configuration

Copy

Copied

{
  "$schema": "https://<slug>.api-se.playground.norce.tech/checkout/norce-adapter/openapi/v1/schemas/norce_adapter.json",
  "id": "norce_adapter",
  "active": true,
  "adapter": {
    "internalUrl": "https://norce-adapter.checkout.playground.internal.norce.tech",
    "publicUrl": "https://<slug>.api-se.playground.norce.tech/checkout/norce-adapter"
  },
  "settings": {
    "clientId": <clientId>,
    "applicationId": <applicationId>
  },
  "api": {
    "identityAddress": "https://identityservice.commerce.test.internal.norce.tech/connect/token",
    "identityClientId": "<identityClientId>",
    "identityClientSecret": "<identityClientSecret>",
    "identityScope": "lab"
  },
  "application": {
    "productUrlPattern": "https://<slug>.admin-se.playground.norce.tech/product/detail/{productId}",
    "imageBaseUrl": "https://<slug>.test.cdn-norce.tech/{{commerceClientId}}"
  },
  "country": {
    "defaultCountry": "SE"
  },
  "features": {
    "shippingChangedHookEnabled": true
  }
}

$schema : Where you and the adapter will find the schema version used for this configuration. Use the public url with your slug and the environment you're using. Will always end with openapi/v1/schemas/norce_adapter.json , where version v1 can change.
id : The configuration identifier, will always be the Norce adapter identifier norce_adapter .
active : If the configuration is active or not.
adapter : How to access the adapter.
- internalUrl : How Norce Checkout services access the adapter.
- publicUrl : How the adapter is accessed publically. The url should contain your slug.
settings : Basic Norce Commerce information.
- clientId : Your Norce Commerce client id.
- applicationId : Your Norce Commerce application id.
api : How to access Norce Commerce. You'll find more information about these fields in the Norce Commerce documentation.
- identityAddress : The identity address, use test for playground and prod for stage and production.
- identityClientId : The Identity client id you want the adapter to use..
- identityClientSecret : The Identity client secret you want the adapter to use..
- identityScope : The scope the adapter should use.
application : Additional application information.
- productUrlPattern : The same pattern you've configured for product urls in your application.
- imageBaseUrl : The same image base url you've configured in your application.
country : Country settings used as a default value or fallback.
- defaultCountry : Default country.
features : Feature toggles for the adapter.
- shippingChangedHookEnabled : This will be improved, read more in the Delivery section.

Delivery

The Norce adapter can manage shippings in two ways:

Full Control : The adapter provides Norce Checkout with the shipping option selected in Norce Commerce. In this case, the order will include shipping information based on the delivery method from Norce Commerce.
Leave to Norce Checkout : The adapter can also allow Norce Checkout to handle shippings. This is useful if you're adding shipping manually during checkout or using an external provider, like Klarna Checkout with Klarna Shipping Assistant. In this case, the Norce adapter should use the External Delivery Method (128), and the method will be updated based on the selection made in Norce Checkout.

A work in progress, this is currently controlled by setting features/shippingChangedHookEnabled to true, and setting Delivery Method to 128 in order to leave it to Norce Checkout. And setting it to false and providing another Delivery Method in your checkout in order for the Norce adapter to take full control.

Copy

Copied

{
  // ...
  "features": {
    "shippingChangedHookEnabled": true
  }
  // ...
}

Create an order

When creating an order you provide some context.

cartReference: The Norce Commerce basket id you want to create a Norce Checkout order from. Required.
culture: Language and region of the customer. Required.
currency: Currency of the purchase, technically not required but few adapters will work with an order without currency. The Norce Checkout admin can also have difficulty displaying an order without currency.
country: Country of purchase, technically not required and will default to the country set in your configuration.

The Norce adapter will start by fetching its configuration and then it will get the Norce Commerce checkout. The adapter will create an order, with basket being mapped to cart. If configured to have full control of delivery, the delivery will be mapped to a shipping.

If the checkout contains customer information the customer in the order will be mapped as well. If a Payer is set, it will be mapped to customer.billing, if ShipTo is set, it will be mapped to customer.shipping. If Payer or ShipTo is missing, it will use Buyer instead.

Updating an Order

Once an order has been created, it's essential to keep the data in both Norce Commerce and Norce Checkout synchronized. The Norce adapter automatically handles updates to Norce Commerce when changes originate from Norce Checkout. However, if changes are made in Norce Commerce first, you must inform the Norce adapter to reflect those changes in Norce Checkout.

Handling Updates from Norce Checkout

When changes are made in Norce Checkout (e.g., a payment provider adapter adds customer information), the Norce adapter detects the update and automatically pushes it to Norce Commerce. This ensures that both systems stay aligned without manual intervention.

Handling Updates from Norce Commerce

If changes are made in Norce Commerce (e.g., adding items to the basket or adjusting item quantities), the Norce adapter is unaware of these updates. In such cases, you need to explicitly inform the Norce adapter by calling Update Order. This will trigger the Norce adapter to synchronize the changes with the order in Norce Checkout.

Example Scenarios

Customer Information : If customer information is updated via a payment provider in Norce Checkout, the Norce adapter will ensure that the data is mirrored in Norce Commerce.
Quantity Changes : If an item's quantity is adjusted in Norce Checkout, the Norce adapter will first update Norce Commerce to account for promotions or other rules, then reflect the updated quantity in Norce Checkout.
Basket Updates : If an item is added to the basket in Norce Commerce, you must notify the Norce adapter to update the order in Norce Checkout and ensure both systems remain in sync.

Payments

When using the Norce adapter we need to use the Norce Checkout Payment Method in Norce Commerce. This allows the adapter to provide Norce Commerce with payment information regardless of what the provider is.

When the Norce Checkout order state is changed to processing the Norce adapter will validate the order, confirming that Norce Checkout and Norce Commerce data is synchronized. It will then validate the payment, in effect storing a copy of the basket. When the state is then changed to completed the payment will be completed. Any changes made to the basket while the payment was being processed are ignored. When the payment is completed the order is available in Norce Commerce.

Example

Consider a customer that enters the checkout, begins the payment process but then realizes that they want to change the quantity of an item before completing the payment process. When the payment process was begun, the order state was changed to processing. When the adapter then tries to update the cart with the modified quantity the order service will first change the state to checkout again. The payment provider adapter will be informed of the state change, able to confirm that the payment has not been completed. The cart change is committed and the payment process can be started again.

Bundles

In Norce Commerce bundles, aka structure articles, are all displayed in the same list with types and references to parent item to make it clear what is a bundle and what are the items in the bundle.

In the Norce Checkout order, cart items instead have a list of items. For a regular item, this list will always be empty. For a bundle you will only see the bundle in the cart item list, and instead see the containing items on the bundle.

Here's a simplified Norce Commerce basket containing a bundle:

Copy

Copied

{
  "Id": 48447,
  "CurrencyId": 2,
  "CurrencyCode": "SEK",
  "Items": [
    {
      "Id": 155001,
      "LineNo": 1,
      "ProductId": 5003,
      "PartNo": "100003",
      "ManufacturerPartNo": "TM3",
      "Name": "Keyboard + Mouse bundle",
      "SubHeader": "A bundle of keys and wheels.",
      "UniqueName": "keyboard-mouse-bundle",
      "Type": 37,
      "Quantity": 1,
      "VatRate": 1.25,
      "PriceDisplay": 244.84,
      "PriceOriginal": 244.84,
      "PriceDisplayIncVat": 306.05,
      "PriceOriginalIncVat": 306.05,
    },
    {
      "Id": 155002,
      "LineNo": 2,
      "ParentLineNo": 1,
      "ProductId": 5001,
      "PartNo": "100001",
      "ManufacturerPartNo": "TM1",
      "Name": "Keyboard",
      "SubHeader": "A board with keys!",
      "UniqueName": "keyboard",
      "Type": 1,
      "Quantity": 1,
      "VatRate": 1.25,
      "PriceDisplay": 167.44,
      "PriceOriginal": 167.44,
      "PriceStandard": 239.2,
      "PriceDisplayIncVat": 209.3,
      "PriceOriginalIncVat": 209.3,
      "PriceStandardIncVat": 299
    },
    {
      "Id": 155003,
      "LineNo": 3,
      "ParentLineNo": 1,
      "ProductId": 5002,
      "PartNo": "100002",
      "ManufacturerPartNo": "TM2",
      "Name": "Mouse",
      "SubHeader": "Now with scroll wheel!",
      "UniqueName": "mouse",
      "Type": 1,
      "Quantity": 1,
      "VatRate": 1.25,
      "PriceDisplay": 77.4,
      "PriceOriginal": 77.4,
      "PriceStandard": 103.2,
      "PriceDisplayIncVat": 96.75,
      "PriceOriginalIncVat": 96.75,
      "PriceStandardIncVat": 129
    }
  ],
  "Summary": {
    "Items": {
      "Amount": 244.84,
      "Vat": 61.21,
      "AmountIncVat": 306.05
    },
    "Total": {
      "Amount": 244.84,
      "Vat": 61.21,
      "AmountIncVat": 306.05
    }
  },
  "PaymentMethodId": 239,
  "DeliveryMethodId": 128
}

And here's a simplified Norce Checkout order cart resulting from the above basket.

Copy

Copied

{
  "reference": "48447",
  "items": [
    {
      "id": "ciElPtzLvSmaZLnDRCpKgzmkcgCx",
      "reference": "155001",
      "name": "Keyboard + Mouse bundle",
      "sku": "100003",
      "productType": "bundle",
      "items": [
        {
          "reference": "155002",
          "name": "Keyboard",
          "sku": "100001",
          "productType": "physical",
          "quantity": 1,
          "price": {
            "includingVat": 209.3,
            "excludingVat": 167.44
          },
          "total": {
            "includingVat": 209.3,
            "excludingVat": 167.44
          },
          "originalTotal": {
            "includingVat": 209.3,
            "excludingVat": 167.44
          },
          "vatRate": 0.25
        },
        {
          "reference": "155003",
          "name": "Mouse",
          "sku": "100002",
          "productType": "physical",
          "quantity": 1,
          "price": {
            "includingVat": 96.75,
            "excludingVat": 77.4
          },
          "total": {
            "includingVat": 96.75,
            "excludingVat": 77.4
          },
          "originalTotal": {
            "includingVat": 96.75,
            "excludingVat": 77.4
          },
          "vatRate": 0.25
        }
      ],
      "quantity": 1,
      "price": {
        "includingVat": 306.05,
        "excludingVat": 244.84
      },
      "total": {
        "includingVat": 306.05,
        "excludingVat": 244.84
      },
      "originalTotal": {
        "includingVat": 306.05,
        "excludingVat": 244.84
      },
      "vatRate": 0.25
    }
  ],
  "total": {
    "includingVat": 306.05,
    "excludingVat": 244.84
  }
}