Skip to main content

nShift Adapter

Overview​

The nShift Adapter integrates nShift Checkout with Norce Checkout, enabling merchants to offer nShift's comprehensive delivery experience within the Norce Commerce platform. nShift provides a flexible checkout solution that allows customers to select from various shipping options including home delivery, pickup points, and time-slotted deliveries from multiple carriers.

This adapter is part of Norce Checkout (NCO) and handles the complete shipping flow from session initialization through order completion. The adapter uses OAuth2 authentication to communicate with nShift's APIs and creates partial shipments when orders are accepted, enabling tracking and fulfillment through nShift's logistics platform.

Capabilities and Supported Flows​

The nShift Adapter supports the following shipping operations:

Delivery Methods:

  • Home delivery
  • Pickup point delivery (service points, lockers, stores)
  • Time-slotted delivery windows
  • Multiple carrier support based on nShift configuration
  • Carrier-specific addons and services

Supported Operations:

  • Create nShift checkout session
  • Get session with shipping options
  • Update session on cart/customer changes
  • Complete session with partial shipment creation
  • Remove session from order
  • Bidirectional synchronization (Norce to nShift and nShift to Norce)

Additional Features:

  • OAuth2 authentication with automatic token refresh
  • Connection ID-based merchant routing
  • Logistics data mapping (weight, dimensions, package contents)
  • Pickup point selection with address details
  • Delivery time estimates
  • Custom fields and addon support
  • Automatic hook registration for change tracking

Prerequisites​

From nShift​

To use the nShift Adapter, you need the following from nShift:

  • An nShift account with Checkout API access enabled
  • OAuth2 credentials (Client ID and Client Secret)
  • Connection ID for your merchant configuration
  • Configured carriers and delivery options in your nShift account
  • Access to nShift's staging environment for development

From Norce​

  • Norce Checkout enabled for your Norce Commerce account
  • A configured merchant and channel in Norce Checkout Admin
  • OAuth2 credentials for API authentication
  • Order with country, culture, and currency set (required for session creation)

Environments​

The nShift Adapter URLs follow this pattern:

EnvironmentAdapter URL Pattern
Productionhttps://{slug}.api-se.norce.tech/checkout/nshift-adapter
Stagehttps://{slug}.api-se.stage.norce.tech/checkout/nshift-adapter
Playgroundhttps://{slug}.api-se.playground.norce.tech/checkout/nshift-adapter

Replace {slug} with your organization's slug provided by Norce.

nShift API environments:

EnvironmentnShift API URL
Productionhttps://api.nshiftportal.com
Token URLhttps://account.nshiftportal.com/idp/connect/token

Setup in Norce Admin​

To configure the nShift Adapter, navigate to Norce Checkout Admin from Norce Commerce Admin by going to Shopping > Checkout. Then:

  1. Go to Configurations in Norce Checkout Admin
  2. Create or edit a configuration for your merchant and channel
  3. Add the nShift Adapter with the following settings:

Required Configuration Fields​

FieldDescription
apiSettings.clientIdYour nShift OAuth2 Client ID
apiSettings.clientSecretYour nShift OAuth2 Client Secret
apiSettings.connectionIdYour nShift Connection ID for merchant routing

Adapter URLs​

FieldDescription
adapter.internalUrlInternal service-to-service URL for callbacks
adapter.publicUrlPublic API URL for external access

Optional Configuration​

FieldDescriptionDefault
apiSettings.tokenUrlOAuth2 token endpoint URLhttps://account.nshiftportal.com/idp/connect/token
apiSettings.optionsBaseUrlBase URL for nShift checkout options APIhttps://api.nshiftportal.com/checkout/options
apiSettings.shipmentsBaseUrlBase URL for nShift shipments APIhttps://api.nshiftportal.com/checkout
options.defaultLanguageCodeDefault language code for nShift checkouten
options.defaultCurrencyCodeDefault currency code for nShift checkoutSEK
options.defaultLocaleIdDefault locale ID for nShift checkouten-US
options.externalIdSourceWhich order property maps to nShift's external ID: OrderId or OrderCartReferenceOrderId

Example Configuration​

{
"$schema": "https://{slug}.api-se.playground.norce.tech/checkout/nshift-adapter/openapi/v1/schemas/nshift_adapter.json",
"id": "nshift_adapter",
"active": true,
"adapter": {
"internalUrl": "https://nshift-adapter.checkout.playground.internal.norce.tech",
"publicUrl": "https://{slug}.api-se.playground.norce.tech/checkout/nshift-adapter"
},
"apiSettings": {
"tokenUrl": "https://account.nshiftportal.com/idp/connect/token",
"optionsBaseUrl": "https://api.nshiftportal.com/checkout/options",
"shipmentsBaseUrl": "https://api.nshiftportal.com/checkout",
"clientId": "your-nshift-client-id",
"clientSecret": "your-nshift-client-secret",
"connectionId": "your-nshift-connection-id"
},
"options": {
"defaultLanguageCode": "en",
"defaultCurrencyCode": "SEK",
"defaultLocaleId": "en-US",
"externalIdSource": "OrderId"
}
}

Configuration Details​

OAuth2 Authentication​

The nShift Adapter uses OAuth2 client credentials flow for authentication. The adapter automatically manages token acquisition and refresh:

  • Tokens are cached in memory with automatic refresh before expiration
  • If a request receives a 401 Unauthorized response, the token is invalidated and refreshed automatically
  • The adapter uses separate HTTP clients for token acquisition and API calls to avoid circular dependencies

Connection ID​

The Connection ID is a merchant-specific identifier that routes requests to the correct nShift merchant configuration. This ID is provided by nShift when you set up your account and determines which carriers, delivery options, and pricing rules apply to your checkout sessions.

Language Codes​

The adapter supports the following language codes for nShift checkout:

en, sv, da, no, fi, de, fr, ru, es, pl, cs, et, nl, it, lv, bg, pt, hu, sk, el, tr, ro

The language is determined from the order's culture (e.g., sv-SE extracts sv) or falls back to the configured default.

External ID Source​

The externalIdSource option controls which Norce order property is mapped to nShift's external ID:

  • OrderId (default): Uses the Norce Checkout order ID (e.g., oJpSLgMu)
  • OrderCartReference: Uses the cart reference (useful when integrating with external systems that track by cart ID)

Test vs Production​

When switching between test and production environments:

  1. Update the apiSettings.tokenUrl, apiSettings.optionsBaseUrl, and apiSettings.shipmentsBaseUrl if using different nShift environments
  2. Use the corresponding nShift OAuth2 credentials for each environment
  3. Update the adapter base URL in your frontend integration

Usage Examples​

Creating an nShift Shipping Session​

To initialize an nShift checkout session, first create a Norce Checkout order with country, culture, and currency set, then create a shipping with the nShift adapter:

POST /api/checkout/v1/orders/{order_id}/shippings
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The nShift Adapter creates a session and returns shipping options:

{
"shippingId": "sGMVlgVNMjCDxsdJaOwmklGEpjM",
"htmlSnippet": "<div id=\"nshift-checkout-container\">...</div>",
"sessionId": "abc123-session-id"
}

The adapter also updates the Norce order with shipping details:

{
"shippings": [
{
"id": "sGMVlgVNMjCDxsdJaOwmklGEpjM",
"adapterId": "nshift_adapter",
"name": "PostNord Home Delivery",
"description": "Delivery: 2025-01-15 - 2025-01-17",
"merchant": "norce-checkout-demo",
"channel": "nshift-b2c",
"orderId": "oAPpsaMj",
"reference": "option-123",
"state": "intent",
"price": {
"includingVat": 79.0,
"excludingVat": 63.2
},
"vatRate": 25,
"attributes": {
"optionId": "option-123",
"carrierId": "postnord",
"carrierProductId": "home-delivery",
"carrierName": "PostNord",
"categoryId": "home",
"valid": true,
"deliveryTime": {
"earliestDate": "2025-01-15",
"latestDate": "2025-01-17",
"description": "1-3 business days"
},
"pickupPoints": [],
"addons": []
}
}
]
}

Getting an Existing Session​

To retrieve the session for an existing shipping (e.g., when the customer returns to checkout):

GET /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Removing a Shipping Session​

To remove an nShift shipping from an order:

POST /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}/remove
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

This sets the shipping state to removed and deletes any hooks registered by the adapter.

Checkout Flow Integration​

Embedding the Widget​

Embed the HTML snippet returned from the create shipping endpoint in your checkout page. The nShift checkout widget handles delivery option display and selection.

<div id="nshift-checkout-container">
<!-- Insert htmlSnippet here -->
</div>

Client-Side Callbacks​

nShift does not inform the adapter directly of changes made through the checkout widget. To keep the Norce order synchronized, you must subscribe to nShift's events and call the appropriate adapter endpoints.

Shipping Changed Event: When the customer selects a different delivery option, call the shipping changed endpoint:

POST /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/shipping-changed
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}

Customer Changed Event: When the customer updates their address in the nShift widget, call the customer changed endpoint:

POST /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/customer-changed
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}

Refer to nShift Developer Documentation for details on subscribing to checkout events.

Example Frontend Integration​

// Subscribe to nShift checkout events
window.nshiftCheckout = window.nshiftCheckout || {};

nshiftCheckout.onShippingOptionChanged = async function(data) {
try {
// Notify the adapter of shipping changes
const response = await fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${shippingId}/shipping-changed`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`,
'x-merchant': merchant,
'x-channel': channel
}
});
if (!response.ok) {
console.error('Failed to sync shipping change:', response.status);
}
} catch (error) {
console.error('Error syncing shipping change:', error);
}
};

nshiftCheckout.onAddressChanged = async function(data) {
try {
// Notify the adapter of customer address changes
const response = await fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${shippingId}/customer-changed`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`,
'x-merchant': merchant,
'x-channel': channel
}
});
if (!response.ok) {
console.error('Failed to sync address change:', response.status);
}
} catch (error) {
console.error('Error syncing address change:', error);
}
};

Backend Callbacks​

The nShift Adapter automatically registers hooks when a session is created to handle changes from other adapters:

Cart Changed Hook​

When the cart is modified (items added/removed, quantities changed), the adapter automatically updates the nShift session with the new cart data. This ensures shipping prices and options reflect the current cart contents.

The adapter sends updated package information including:

  • Total price
  • Article details (SKU, quantity, weight, volume)
  • Package contents description

Customer Changed Hook​

When customer address information changes in the Norce order (e.g., from a payment adapter), the adapter updates the nShift session with the new receiver information including name, address, email, and phone.

State Changed Hook​

When the order state changes, the adapter reacts accordingly:

  • Processing: Validates that the nShift session matches the Norce shipping (price, name)
  • Accepted: Completes the session by creating a partial shipment in nShift

Completing the Session​

When the order is completed (typically driven by a payment adapter), the nShift Adapter automatically reacts to the state change and creates a partial shipment in nShift. This is a mandatory step in the nShift workflow that:

  • Creates a shipment record in nShift's system
  • Enables tracking and fulfillment through nShift
  • Returns a shipment ID that can be used for carrier integration

The partial shipment includes:

  • Session ID and selected option ID
  • Order ID (based on externalIdSource configuration)
  • Receiver information (name, address, contact details)
  • Selected addons, field values, pickup point, and time slot (if applicable)

Data Mapping​

Cart to nShift​

The adapter maps the following cart data to nShift:

Norce FieldnShift FieldNotes
order.currencycurrencyCodeCurrency code (e.g., SEK, EUR)
order.culturelanguageCodeExtracted from culture (e.g., sv from sv-SE)
cart.total.includingVattotalPriceTotal cart price including VAT
cart.items[].skupackages[].articles[].articleNoProduct SKU or reference
cart.items[].quantitypackages[].articles[].quantityItem quantity
cart.items[].logistics.weightpackages[].articles[].weightKgWeight in kg (converted from grams)
cart.items[].logistics.height/width/lengthpackages[].articles[].volumeCm3Volume in cm3 (converted from mm3)
cart.items[].logistics.tagspackages[].articles[].tagsLogistics tags
cart.items[].namepackages[].contentsPackage contents description
customer.firstName/lastNamereceiver.nameCombined customer name
customer.addresses[].streetreceiver.address1Shipping address
customer.addresses[].postalCodereceiver.postalCodePostal code
customer.addresses[].cityreceiver.cityCity
customer.addresses[].countryCodereceiver.countryCountry code
customer.emailreceiver.emailCustomer email
customer.phonereceiver.phoneCustomer phone
customer.mobilereceiver.mobileCustomer mobile

nShift to Shipping​

The adapter maps the following nShift option data to the Norce shipping:

nShift FieldNorce FieldNotes
option.optionIdshipping.referencenShift option ID
option.nameshipping.nameShipping option name
option.descriptionshipping.descriptionOption description with delivery time
option.priceshipping.price.includingVatShipping price including VAT
option.taxRateshipping.vatRateVAT rate percentage
option.carrierIdshipping.attributes.carrierIdCarrier identifier
option.carrierProductIdshipping.attributes.carrierProductIdCarrier product ID
option.carrierNameshipping.attributes.carrierNameCarrier display name
option.categoryIdshipping.attributes.categoryIdDelivery category
option.deliveryTimeshipping.attributes.deliveryTimeDelivery time estimates
option.pickupPointsshipping.attributes.pickupPointsAvailable pickup points
option.addonsshipping.attributes.addonsAvailable addons
option.fieldsshipping.attributes.fieldsCustom input fields
option.timeSlotsshipping.attributes.timeSlotsAvailable time slots

Error Handling and Troubleshooting​

Common Error Scenarios​

Session Creation Fails (Validation Error): Ensure the order has country, culture, and currency set. These are required fields for creating an nShift session.

Session Creation Fails (409 Conflict): An nShift shipping already exists for this order. Remove the existing shipping using the remove endpoint or use a different order.

Authentication Error (401 Unauthorized): Verify your OAuth2 credentials (Client ID and Client Secret) are correct. The adapter will automatically attempt to refresh the token on 401 errors.

Connection Not Found: Verify your Connection ID is correct and active in your nShift account.

Empty Cart Error: The order must have at least one item in the cart to create or update an nShift session.

Session Validation Fails: During order processing, the adapter validates that the Norce shipping matches the nShift session. If the price or name doesn't match, validation fails. This can happen if the session was modified outside of the normal flow.

Debugging​

  1. Check the Norce order shipping state and attributes
  2. Verify the nShift session status in nShift's dashboard
  3. Ensure client-side callbacks are correctly calling the adapter endpoints
  4. Check that the order has valid country, culture, and currency values
  5. Verify the OAuth2 credentials and Connection ID configuration
  6. Check the adapter logs for detailed error messages

Shipping States​

The adapter uses the following shipping states:

StateDescription
intentShipping session created, awaiting customer selection
processingOrder is being processed, session validated
confirmedSession completed successfully, partial shipment created
removedShipping removed from order

Norce Checkout API References​

nShift Adapter API​

Norce Checkout Overview​

nShift Documentation​