Shipping Adapters Overview
Shipping adapters handle delivery selection and logistics in Norce Checkout. They integrate with external shipping providers and Transport Management Systems (TMS) to provide shipping options, track deliveries, and synchronize shipping details with the checkout order.
For general requirements and access details, see How to access Norce Checkout.
API Environments and URLs
All Norce Checkout shipping adapters use the same URL pattern:
| Environment | URL Pattern |
|---|---|
| Production | https://{slug}.api-se.norce.tech/checkout/{adapter}-adapter |
| Stage | https://{slug}.api-se.stage.norce.tech/checkout/{adapter}-adapter |
| Playground | https://{slug}.api-se.playground.norce.tech/checkout/{adapter}-adapter |
Replace {slug} with your unique Norce instance slug and {adapter} with the provider-specific name (e.g., ingrid).
How Shipping Adapters Work
Shipping adapters primarily operate by listening to shipping hooks on the Norce Checkout order. When shipping-related changes occur, the adapter is notified and can update the order accordingly.
Hook-Based Integration
When a shipping adapter is activated for an order, it registers hooks that subscribe to shipping changes:
{
"subscribeTo": "/shippings",
"invoke": "https://{adapter}.checkout.internal.norce.tech/api/v1/orders/{orderId}/shipping-changed"
}This allows the adapter to:
- React to shipping selection: When a customer selects a shipping option in the checkout UI, the adapter receives a callback
- Update order details: The adapter updates the order's
shippingsarray with delivery details, pricing, and carrier information - Synchronize totals: Shipping costs are reflected in the order total, ensuring payment adapters have accurate amounts
Shipping Data Flow
- Customer selects shipping: The checkout UI triggers a shipping change on the order
- Hook invoked: The Order Service calls the shipping adapter's registered hook
- Provider interaction: The adapter communicates with the external shipping provider/TMS
- Order updated: The adapter writes updated shipping details back to the order, including:
- Carrier and service information
- Delivery pricing (including VAT)
- Pickup location details (if applicable)
- TMS reference for tracking
Integration with Payment Adapters
Some payment adapters (like Klarna Checkout) can also provide shipping options through their own shipping assistants. In these cases, the payment adapter handles shipping selection directly and updates the order's shipping details. Standalone shipping adapters are used when you want dedicated shipping provider integration independent of the payment flow.