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:
| Environment | Adapter URL Pattern |
|---|---|
| Production | https://{slug}.api-se.norce.tech/checkout/nshift-adapter |
| Stage | https://{slug}.api-se.stage.norce.tech/checkout/nshift-adapter |
| Playground | https://{slug}.api-se.playground.norce.tech/checkout/nshift-adapter |
Replace {slug} with your organization's slug provided by Norce.
nShift API environments:
| Environment | nShift API URL |
|---|---|
| Production | https://api.nshiftportal.com |
| Token URL | https://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:
- Go to Configurations in Norce Checkout Admin
- Create or edit a configuration for your merchant and channel
- Add the nShift Adapter with the following settings:
Required Configuration Fields
| Field | Description |
|---|---|
apiSettings.clientId | Your nShift OAuth2 Client ID |
apiSettings.clientSecret | Your nShift OAuth2 Client Secret |
apiSettings.connectionId | Your nShift Connection ID for merchant routing |
Adapter URLs
| Field | Description |
|---|---|
adapter.internalUrl | Internal service-to-service URL for callbacks |
adapter.publicUrl | Public API URL for external access |
Optional Configuration
| Field | Description | Default |
|---|---|---|
apiSettings.tokenUrl | OAuth2 token endpoint URL | https://account.nshiftportal.com/idp/connect/token |
apiSettings.optionsBaseUrl | Base URL for nShift checkout options API | https://api.nshiftportal.com/checkout/options |
apiSettings.shipmentsBaseUrl | Base URL for nShift shipments API | https://api.nshiftportal.com/checkout |
options.defaultLanguageCode | Default language code for nShift checkout | en |
options.defaultCurrencyCode | Default currency code for nShift checkout | SEK |
options.defaultLocaleId | Default locale ID for nShift checkout | en-US |
options.externalIdSource | Which order property maps to nShift's external ID: OrderId or OrderCartReference | OrderId |
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:
- Update the
apiSettings.tokenUrl,apiSettings.optionsBaseUrl, andapiSettings.shipmentsBaseUrlif using different nShift environments - Use the corresponding nShift OAuth2 credentials for each environment
- 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
externalIdSourceconfiguration) - 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 Field | nShift Field | Notes |
|---|---|---|
order.currency | currencyCode | Currency code (e.g., SEK, EUR) |
order.culture | languageCode | Extracted from culture (e.g., sv from sv-SE) |
cart.total.includingVat | totalPrice | Total cart price including VAT |
cart.items[].sku | packages[].articles[].articleNo | Product SKU or reference |
cart.items[].quantity | packages[].articles[].quantity | Item quantity |
cart.items[].logistics.weight | packages[].articles[].weightKg | Weight in kg (converted from grams) |
cart.items[].logistics.height/width/length | packages[].articles[].volumeCm3 | Volume in cm3 (converted from mm3) |
cart.items[].logistics.tags | packages[].articles[].tags | Logistics tags |
cart.items[].name | packages[].contents | Package contents description |
customer.firstName/lastName | receiver.name | Combined customer name |
customer.addresses[].street | receiver.address1 | Shipping address |
customer.addresses[].postalCode | receiver.postalCode | Postal code |
customer.addresses[].city | receiver.city | City |
customer.addresses[].countryCode | receiver.country | Country code |
customer.email | receiver.email | Customer email |
customer.phone | receiver.phone | Customer phone |
customer.mobile | receiver.mobile | Customer mobile |
nShift to Shipping
The adapter maps the following nShift option data to the Norce shipping:
| nShift Field | Norce Field | Notes |
|---|---|---|
option.optionId | shipping.reference | nShift option ID |
option.name | shipping.name | Shipping option name |
option.description | shipping.description | Option description with delivery time |
option.price | shipping.price.includingVat | Shipping price including VAT |
option.taxRate | shipping.vatRate | VAT rate percentage |
option.carrierId | shipping.attributes.carrierId | Carrier identifier |
option.carrierProductId | shipping.attributes.carrierProductId | Carrier product ID |
option.carrierName | shipping.attributes.carrierName | Carrier display name |
option.categoryId | shipping.attributes.categoryId | Delivery category |
option.deliveryTime | shipping.attributes.deliveryTime | Delivery time estimates |
option.pickupPoints | shipping.attributes.pickupPoints | Available pickup points |
option.addons | shipping.attributes.addons | Available addons |
option.fields | shipping.attributes.fields | Custom input fields |
option.timeSlots | shipping.attributes.timeSlots | Available 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
- Check the Norce order shipping state and attributes
- Verify the nShift session status in nShift's dashboard
- Ensure client-side callbacks are correctly calling the adapter endpoints
- Check that the order has valid country, culture, and currency values
- Verify the OAuth2 credentials and Connection ID configuration
- Check the adapter logs for detailed error messages
Shipping States
The adapter uses the following shipping states:
| State | Description |
|---|---|
intent | Shipping session created, awaiting customer selection |
processing | Order is being processed, session validated |
confirmed | Session completed successfully, partial shipment created |
removed | Shipping removed from order |