Ingrid Shipping Adapter

Overview

The Ingrid Adapter integrates Ingrid Delivery Checkout with Norce Checkout. It enables merchants to offer dynamic shipping options including home delivery, pickup points, and scheduled delivery windows directly within their checkout flow. Changes made in Norce Checkout are synced with Ingrid and vice versa. Read more on Ingrid Developer Documentation.

Environments

There are three environments that you can use. Replace {slug} with your merchant slug.

Getting Started as a Partner

To use the Ingrid Shipping adapter, you need to set up your Ingrid account and configure the adapter in Norce Checkout Admin.

Prerequisites

Before configuring the adapter, ensure you have the following from Ingrid:

1. API Key: Obtain your API key from your Ingrid account
2. API URL: The Ingrid API endpoint for your environment (staging or production)

Ingrid API Environments

Configuration

Add your configuration for the Ingrid Shipping adapter in Norce Checkout Admin. The configuration requires:

Optional Configuration

Example Configuration

{
  "$schema": "https://checkout-configuration.norce.tech/schemas/ingrid_adapter.json",
  "id": "ingrid_adapter",
  "active": true,
  "adapter": {
    "internalUrl": "https://ingrid-adapter.checkout.playground.internal.norce.tech",
    "publicUrl": "https://{slug}.api-se.playground.norce.tech/checkout/ingrid-adapter"
  },
  "apiSettings": {
    "apiKey": "your-ingrid-api-key",
    "apiUrl": "https://api-stage.ingrid.com"
  },
  "options": {
    "useAddressForm": false,
    "useMinimalSearchAddress": false,
    "externalIdSource": "OrderId"
  }
}

Create Shipping

To get an Ingrid Delivery Checkout session with shipping options, create a shipping using the Ingrid 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 Ingrid adapter will fetch the order, map it to Ingrid's format, and create a session. The response contains the Norce shipping ID, the Ingrid session ID, and an HTML snippet for embedding the widget.

{
  "shippingId": "sGMVlgVNMjCDxsdJaOwmklGEpjM",
  "htmlSnippet": "<div id=\"shipwallet-container\">...</div>",
  "sessionId": "VM2-a1bc234...",
  "useAddressForm": false
}

Using the Response with the Ingrid Widget

The response contains an htmlSnippet that includes the Ingrid widget initialization script and container. Insert this snippet into your checkout page where you want the delivery options to appear.

<!-- Widget container - insert the htmlSnippet here -->
<div id="shipwallet-container">
  <!-- The htmlSnippet from the API response goes here -->
</div>

For detailed widget integration instructions, see the Ingrid Frontend Integration documentation.

<!-- Example: Embedding the Ingrid widget -->
<script>
// After calling the Create Shipping endpoint and receiving the response:
const response = /* response from POST /api/checkout/v1/orders/{order_id}/shippings */;
const orderId = /* your order ID */;
const shippingId = response.shippingId;
const merchant = /* your merchant ID */;
const channel = /* your channel ID */;

// Insert the HTML snippet into your page
document.getElementById('shipwallet-container').innerHTML = response.htmlSnippet;

// Initialize the Ingrid event listener
window._sw = window._sw || function() { (window._sw.q = window._sw.q || []).push(arguments); };

// Listen for shipping option changes
_sw('on', 'shipping_option_changed', async function(data) {
  // Call the shipping-changed endpoint to update Norce
  await fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${shippingId}/shipping-changed`, {
    method: 'POST',
    headers: {
      'x-merchant': merchant,
      'x-channel': channel,
      'Authorization': 'Bearer ' + token
    }
  });
});

// Only needed when using address form mode (useAddressForm: true)
_sw('on', 'address_changed', async function(data) {
  await fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${shippingId}/customer-changed`, {
    method: 'POST',
    headers: {
      'x-merchant': merchant,
      'x-channel': channel,
      'Authorization': 'Bearer ' + token
    }
  });
});
</script>

Get Shipping Session

To retrieve an existing Ingrid session with the latest shipping data, use the GET endpoint:

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}

This returns the same structure as the create endpoint, allowing you to re-render the widget if needed.

Client-Side Callbacks

For more details, see the Ingrid Frontend Integration documentation.

Listening to Ingrid Events

The Ingrid widget uses a global _sw function to register event listeners. Set up your listeners after the widget is loaded:

// Initialize the Ingrid event listener
window._sw = window._sw || function() { (window._sw.q = window._sw.q || []).push(arguments); };

// Called when customer selects a shipping option
_sw('on', 'shipping_option_changed', async function(data) {
  await fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${shippingId}/shipping-changed`, {
    method: 'POST',
    headers: {
      'x-merchant': merchant,
      'x-channel': channel,
      'Authorization': 'Bearer ' + token
    }
  });
});

Shipping Changed

When the shipping_option_changed event is triggered, call the shipping changed endpoint to update the Norce order with the user's selection:

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}
Authorization: Bearer {token}

Customer Changed (Address Form Mode Only)

When using address form mode (useAddressForm: true), listen for the address_changed event and call the customer changed endpoint to sync address data from Ingrid to Norce:

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}
Authorization: Bearer {token}

Automatic Updates

Cart Changed

When items in the cart change, the adapter receives a callback and updates the Ingrid session with the new cart data. This ensures that shipping prices and availability are always accurate based on the current cart contents.

Customer Changed (Search Address Mode)

When customer address changes in Norce and the adapter is configured with useAddressForm: false (the default), the adapter automatically updates Ingrid with the new address. This hook is not registered when using address form mode, as customer data flows from Ingrid to Norce instead.

State Changed

When the order state changes, the adapter reacts accordingly:

• Processing: Validates the Ingrid session to ensure it's ready for completion
• Accepted: Completes the Ingrid session, finalizing the delivery selection

Completing the Session

As you complete your order (usually driven by a payment adapter), the Ingrid adapter will react to the state change and complete the session in Ingrid. The shipping object will then contain the Ingrid delivery reference (tos_id) in the tmsReference field.

Widget Integration

The Ingrid Delivery Checkout widget is embedded in your frontend using the htmlSnippet returned from the adapter. The widget provides a user interface for selecting shipping options, pickup points, and delivery time windows.

For detailed widget integration instructions, see the Ingrid Frontend Integration documentation.

Integration Modes

The adapter supports two integration modes controlled by the useAddressForm configuration option:

Search Address Mode (default): Customer address from the Norce order is sent to Ingrid. Delivery options are displayed based on the provided address. Address changes in Norce are automatically synced to Ingrid via backend hooks.

Address Form Mode: Ingrid's integrated address form handles address collection. Customer information flows from Ingrid back to the Norce order via the client-side customer-changed callback.

Remove Shipping

To remove an Ingrid shipping session 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 will mark the shipping as removed in the Norce order.

Troubleshooting

Common Errors

• Validation Error: Ensure order has country, culture, and currency set before creating a session.
• 409 Conflict: An Ingrid shipping already exists for this order.
• Empty Cart Error: Order must have at least one item.
• Session Expired: Create a new shipping session.

Shipping States

Links and References

• Ingrid Adapter OpenAPI Specification
• Ingrid Developer Documentation (External)
• Ingrid Frontend Integration (External)