Norce adapter

For a high-level architectural overview and visual flow diagrams, see the Norce Adapter Solution Overview.

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.

https://{slug}.api-se.{environment}.norce.tech/checkout/norce-adapter/openapi/v2/schemas/norce_adapter.json

Example configuration

{
  "$schema": "https://{slug}.api-se.playground.norce.tech/checkout/norce-adapter/openapi/v2/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://{slug}.api-se.norce.tech/identity/1.0",
    "identityClientId": "{identityClientId}",
    "identityClientSecret": "{identityClientSecret}",
    "identityScope": "playground"
  },
  "application": {
    "productUrlPattern": "https://{slug}.admin-se.playground.norce.tech/product/detail/{productId}",
    "imageBaseUrl": "https://{slug}.playground.cdn-norce.tech",
    "lengthUnit": "cm",
    "weightUnit": "kg"
  },
  "country": {
    "defaultCountry": "SE"
  },
  "features": {
    "mapShippingFromNorceCommerce": true
  },
  "order": {
    "customerType": "Person"
  },
  "logistics": {
    "tags": {
      "123": "bulky",
      "456": "dangerous",
      "524": "dangerousGoods=true",
      "789": "toxicLevel:high"
    },
    "leadTimeApplicationMode": "Always",
    "excludeWeekendsFromLeadTime": false
  },
  "validationRules": {
    "validateCustomerBillingEmail": false
  }
}

• $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/v2/schemas/norce_adapter.json, where version v2 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: The internal URL for the Norce Adapter. The environment can be one of the following: playground, stage, prod, or the name of an enterprise environment such as acme-corp-stage or acme-corp-prod. If you are using the multi-tenant prod environment, you can skip specifying the environment and simply use https://norce-adapter.checkout.internal.norce.tech.
  • publicUrl: The public URL for the Norce Adapter. The {slug} represents your merchant identifier. The environment can be one of the following: playground, stage, prod, or the name of an enterprise environment. If you are using the multi-tenant prod environment, you can skip specifying the environment and simply use https://{slug}.api-se.norce.tech/checkout/norce-adapter.
• settings: Basic Norce Commerce information.
  • clientId: Your Norce Commerce client id, provided to you by Norce.
  • applicationId: Your Norce Commerce application id, configured in Norce Commerce Admin.
• api: How to access Norce Commerce. You'll find more information about these fields in the Norce Commerce documentation.
  • identityAddress: The URL used to access the identity provider. The {slug} represents your merchant identifier.
  • identityClientId: Client ID used to access Norce Commerce resources. Generated in Norce Admin when the OAuth user is created.
  • identityClientSecret: Client secret used to access Norce Commerce resources. Generated in Norce Admin when the OAuth user is created.
  • identityScope: The scope passed to the identity server. playground, stage, and prod are the only environments to be used by partners. test and rc are only for Norce internal use.
• application: Additional application information.
  • productUrlPattern: The same pattern you've configured for product urls in your application.
  • imageBaseUrl: The base URL for accessing Norce Commerce images, typically pointing to a CDN network. For production, you can omit the environment and directly use https://{slug}.cdn-norce.tech.
  • lengthUnit: Specifies the base unit of length used by the merchant. Supported units: mm, cm, m. Norce Commerce uses cm as default. If a different unit is used, this setting must be updated to ensure correct conversion to millimeters in the Norce checkout order.
  • weightUnit: Specifies the base unit of weight used by the merchant. Supported units: mg, g, kg, t. Norce Commerce uses kg as default. If a different unit is used, this setting must be updated to ensure correct conversion to grams in the Norce checkout order.
• country: Country settings used as a default value or fallback.
  • defaultCountry: The default country for the channel, used when creating an order if no country code is provided in the request context. Follows the ISO 3166 alpha-2 format.
• features: Feature toggles for the adapter.
  • mapShippingFromNorceCommerce: Specifies whether the shipping configured in Norce Commerce should be mapped to the checkout order as the selected shipping method. Read more in the Delivery section.
  • stateCompletedNotificationDelay: Delay in milliseconds. If provided, the notification of order state reaching completed will be delayed, in effect delaying when the Checkout order is turned into a Commerce order. This enables you to perform any final touches on the Checkout order.
  • usePlaceholderItem: When enabled, empty baskets are mapped to orders containing a placeholder item for compatibility with upstream adapters that require non-empty orders, such as the Ingrid and Walley adapters. A virtual item with a price of zero is added to the checkout order so that sessions with these adapters can still be created. The placeholder item is automatically removed as soon as the customer adds an item to the basket. The Norce Adapter will not allow purchases when the order contains a placeholder item.
• order: Order configuration.
  • customerType: Forces the customer type on orders. Organization overrides order customer type. Person (default) uses the buyer type from Norce Commerce if present.
  • consentCheckboxes: An array of consent checkbox configurations, each with an id, localized text (keyed by culture code, e.g. sv-SE), checked (default state), and required (whether checkout can be completed without checking).
• logistics: Logistics configuration for cart items.
  • tags: A mapping of Norce Commerce flag id seeds to tag names. If a product has a flag matching a configured id, the corresponding tag is added to the cart item logistics. The tag value can be a simple name (e.g. "bulky"), or include a separator such as =, :, or ; to express key-value pairs (e.g. "dangerousGoods=true", "toxicLevel:high").
  • isDropShipOnlyTag: Name of the tag to be created on cart item logistics if the product is set to IsDropShipOnly.
  • leadTimeApplicationMode: Specifies when to add lead time to the delivery date. Always adds lead time regardless of stock level, OnlyWhenOutOfStock adds lead time only when the product is out of stock.
  • excludeWeekendsFromLeadTime: If true, weekends (Saturday and Sunday) are excluded from lead time calculation.
• validationRules: Configuration for validation rules applied by the Norce Adapter.
  • validateCustomerBillingEmail: Enables validation of the customer billing email address. If set to true, the Norce Adapter will validate that the billing email is present.

Norce Commerce Info Types

The Norce adapter writes checkout-related data back to the Norce Commerce basket and order using info types. These info types are optional and the order will still be exported without them, but if you want this data available on the basket and order they must be configured in Norce Commerce.

Core Info Types

The following info types are always written to the basket when the order state changes:

Conditional Info Types

The following info types are written to the basket when the corresponding data is available on the Norce Checkout order:

Delivery

The Norce adapter can manage shipping methods 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 shipping. This is useful if you're adding shipping manually during checkout or using an external provider, like Ingrid or nShift. It also applies if you're using a Payment Service Provider (PSP) with built-in shipping selection, such as Kustom Checkout with Shipping Assistant, Qliro Checkout with integrated shipping, or Walley Checkout with delivery module. 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.

This is controlled by the features/mapShippingFromNorceCommerce setting:

• Set to true if no checkout adapters are available for selecting shipping. The adapter will map the shipping configured in Norce Commerce to the checkout order.
• Set to false if a PSP adapter with integrated shipping selection is enabled, or if you use a separate adapter (e.g., Ingrid) that allows users to select and apply shipping during checkout. Use the External Delivery Method (128) in Norce Commerce to leave shipping selection to Norce Checkout.

{
  "features": {
    "mapShippingFromNorceCommerce": true
  }
}

Features

The features section provides feature toggles that control specific adapter behaviors. These are all optional and have sensible defaults.

• mapShippingFromNorceCommerce: Controls whether shipping is sourced from Norce Commerce or managed by Norce Checkout. Defaults to false. See the Delivery section for details.
• stateCompletedNotificationDelay: Introduces a delay (in milliseconds) before the adapter processes the order completion notification. This gives you time to perform any final modifications on the Checkout order before it is turned into a Commerce order. If not set, the notification is processed immediately.
• usePlaceholderItem: When enabled, empty baskets are mapped to orders containing a virtual placeholder item with a price of zero. This is useful for compatibility with upstream adapters that do not support empty carts, such as the Ingrid and Walley adapters. The placeholder item is automatically removed as soon as the customer adds an item to the basket. The Norce Adapter will not allow purchases when the order contains a placeholder item.

{
  "features": {
    "mapShippingFromNorceCommerce": true,
    "stateCompletedNotificationDelay": 5000,
    "usePlaceholderItem": false
  }
}

Logistics

The logistics section configures how the adapter maps product logistics data from Norce Commerce to the Norce Checkout order. This includes tagging products for shipping rules, calculating lead times, and identifying drop-ship products.

• tags: Maps Norce Commerce flag id seeds to tag names on cart item logistics. The flag id seed is the id found in the URL when editing a flag in Norce Admin (e.g. product/flag/flag/123). If a product has a matching flag, the corresponding tag is added to the cart item. Tags can be simple names (e.g. "bulky") or key-value pairs using separators like =, :, or ; (e.g. "dangerousGoods=true", "toxicLevel:high").
• isDropShipOnlyTag: Specifies the tag name to be added to cart item logistics when the product is marked as drop-ship only in Norce Commerce.
• leadTimeApplicationMode: Controls when lead time is added to the delivery date. Always adds lead time regardless of stock level. OnlyWhenOutOfStock adds lead time only when the product is out of stock.
• excludeWeekendsFromLeadTime: When set to true, weekends (Saturday and Sunday) are excluded from the lead time calculation.

{
  "logistics": {
    "tags": {
      "123": "bulky",
      "456": "dangerous",
      "524": "dangerousGoods=true",
      "789": "toxicLevel:high"
    },
    "isDropShipOnlyTag": "dropShipOnly",
    "leadTimeApplicationMode": "Always",
    "excludeWeekendsFromLeadTime": false
  }
}

Validation Rules

The validationRules section allows you to enable additional validation checks performed by the Norce Adapter during order processing.

• validateCustomerBillingEmail: When set to true, the adapter validates that the customer has provided a billing email address. If the email is missing, the validation will fail. This is useful when your checkout flow requires a billing email to be present before completing the order.

{
  "validationRules": {
    "validateCustomerBillingEmail": 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.

Note: For NCO, the Admin payment method is always Norce Checkout (ID 239). Provider-specific settings are managed via the NCO Configuration API, not the legacy Shopping settings.

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:

{
  "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.

{
  "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
  }
}