Ingrid

Ingrid’s Delivery Platform lets a merchant present tailored delivery options built from their own shipping rules and carrier setup. Kustom connects to it through the Ingrid Headless TMS connector in the Kustom Shipping Assistant, which fetches options from Ingrid during checkout and maps them onto Kustom’s order model — so the merchant works with one consistent order regardless of where the options came from. This page is the field-level contract: what to configure, what each attribute is populated from and what changes when an order is fulfilled by more than one shipment.

How the two systems divide the work

Ingrid owns the carriers, delivery options, pickup locations, addons and the merchant-facing tooling in the Ingrid Merchant Platform (IMP).

Kustom Checkout, through KSA and the Ingrid Headless connector, requests options from Ingrid, renders them to the buyer and records the buyer’s choice on the order.

The lifecycle runs: order creation, shipping selection while the order is checkout_incomplete, completion, then shipment booking with Ingrid after the fact.

Setting up

In Ingrid

Sign up for the Ingrid Merchant Platform and configure your carriers, delivery options and shipping settings there. From Ingrid you need:

• Your Ingrid Site ID
• Your Ingrid private key — the plain key, not the base64-encoded variant

In Kustom

Follow the general Shipping Assistant setup, with these Ingrid-specific details.

Portal field	Value
TMS	Ingrid Headless. Available in both Playground and Production
Identifier	Your Ingrid Site ID
Key	Your Ingrid private key, plain and not base64-encoded

In Playground the connector talks to Ingrid’s staging environment. In Production, it talks to Ingrid’s production environment.

Digital products are the one deviation from the general guide. They are handled on Ingrid’s side by tagging them with a digital tag, not through Kustom configuration, so skip the general guide’s digital-products step entirely.

Everything else — activating KSA in the Portal, triggering KSA in the checkout payload and verifying in Playground — is unchanged.

Merchants running a dual-iframe checkout

Some merchants run an Ingrid iframe above a Kustom iframe during a transition period, and need to keep collecting a shipping address without yet showing Ingrid-sourced options inside Kustom. Pass options.tms_configuration_override.disabled as true when creating the order: Kustom then collects the address but doesn’t fetch options from Ingrid.

Pre-purchase: how the selected option is populated

While the order’s status is checkout_incomplete, selected_shipping_option — present in both the order response and the callbacks — describes the buyer’s choice. Its fields come from Ingrid like this:

Field	Mapped from
id	The shipping option ID generated by Ingrid
name	The display_name of the Ingrid delivery_category, falling back to the carrier’s product name
description	Not provided
promo	Not provided
price	The price of the Ingrid delivery_option
preselected	Not provided
tax_rate	Defaulted by KSA from a per-country table — see below
tax_amount	Derived from that defaulted tax_rate
shipping_method	KSA’s mapping of Ingrid’s delivery type and location type
tms_reference	Post-purchase only — Ingrid’s session ID
tos_id	Post-purchase only

Shipping method mapping

shipping_method is derived from Ingrid’s delivery_type and, where present, location_type:

Ingrid delivery type	Ingrid location type	KSA shipping_method
—	LOCATION_TYPE_UNSPECIFIED	No effect — falls through to the delivery type rows below
—	LOCKER	BoxUnreg
—	STORE	PickUpPoint
—	POSTOFFICE	PickUpPoint
—	MANNED	PickUpPoint
DELIVERY_TYPE_UNSPECIFIED	—	Undefined
DELIVERY	—	Home
MAILBOX	—	Postal
PICKUP	—	PickUpPoint, or Home when no locations are available
INSTORE	—	PickUpStore, or Home when no locations are available

Delivery details

selected_shipping_option.delivery_details carries the carrier and logistics detail:

• carrier — KSA’s supported carrier, decoded from the prefix of Ingrid’s carrier product ID, falling back to Ingrid’s carrier name
• class — always STANDARD
• product.identifier — Ingrid’s carrier product ID, post-purchase only
• product.name — Ingrid’s carrier name, post-purchase only
• timeslot.id — Ingrid’s shipping option ID for the timeslot
• timeslot.start, timeslot.end — the timeslot bounds
• pickup_location.id — Ingrid’s numeric location ID
• pickup_location.name, pickup_location.address — the location

Selected addons

selected_shipping_option.selected_addons is an array with one entry per chosen addon: display_name, type (the addon’s external_id in Ingrid, or Ingrid’s addon ID when it has none), price and external_id (Ingrid’s addon ID).

Tax on shipping options is defaulted, not calculated

Ingrid doesn’t calculate tax, so KSA supplies the selected option’s tax_rate itself and derives tax_amount from it. By default that rate comes from a per-country table — 25% for SE, NO and DK, 25.5% for FI, 19% for DE, and 25% for any country not listed. In a market the table doesn’t cover, that fallback is a guess and you’ll overpay tax if you leave it.

Two other modes exist and are enabled per merchant by Kustom: one takes the lowest tax rate among the order’s non-shipping lines, the other derives an effective rate proportionally across the cart’s tax groups. Ask which one your account is on before assuming the table applies.

Override it by implementing the shipping option update callback and returning one or more shipping_fee order lines on the order in the callback response. Those lines replace the defaulted tax_rate and tax_amount. Compute the rate from the cart, not from a constant.

Merchant references must be sent before completion

merchant_reference1 — or merchant_reference2 when the first is missing — is propagated to Ingrid as the delivery’s external_id, so that orders can be found in the Ingrid Merchant Platform.

Send them before the order is completed. Two consequences follow from Kustom not updating the Ingrid session after completion:

• If the references are missing at completion time, Kustom sends its own order_id as the Ingrid delivery’s external_id instead.
• Sending merchant references to the Order Management API afterwards will not reach Ingrid. There’s no way to correct it later.

Post-purchase: booking the shipment

Shipping information stays available after completion. Both tms_reference and tos_id are on selected_shipping_option, in the Checkout API and the Order Management API alike.

To fulfill the order, create and book the shipment with Ingrid through Ingrid’s SOM API, passing the tos_id from the order’s selected_shipping_option. Because the Ingrid Headless API shares most of its model with Ingrid’s delivery checkout API, the tos_id alone is enough — Ingrid fills in the rest. If another system needs more detail, use the tos_id to fetch the full shipment information from Ingrid’s sessions_summaries.list API.

Split shipments

An order can be fulfilled by more than one shipment — goods from multiple warehouses, or items that must ship separately for any other reason. The pre-purchase and post-purchase flows are nearly identical. What changes is the order structure.

Deliveries

The deliveries array describes each shipment. Every order line except those of type gift_card and store_credit must be assigned to one, through order_lines[].shipping_attributes.delivery_id. There’s no limit on the number of deliveries.

{
  "deliveries": [
    {
      "id": "Shipment-1",
      "title": "Shipment 1",
      "description": "Refrigerated goods",
      "readiness": [
        {
          "earliest": "2026-03-16T08:40:34.865Z",
          "latest": "2026-03-17T08:40:34.865Z",
          "attributes": ["premium"]
        }
      ],
      "origins": [{ "external_id": "cold-storage-1" }]
    },
    {
      "id": "Shipment-2",
      "title": "Shipment 2",
      "description": "Dry goods",
      "readiness": [
        {
          "earliest": "2026-03-16T08:40:34.865Z",
          "latest": "2026-03-17T08:40:34.865Z",
          "attributes": ["economy"]
        }
      ],
      "origins": [{ "external_id": "warehouse-1" }]
    }
  ],
  "order_lines": [
    {
      "type": "physical",
      "reference": "salmon-001",
      "name": "Fresh Salmon Fillet",
      "quantity": 1,
      "shipping_attributes": { "delivery_id": "Shipment-1" }
    },
    {
      "type": "physical",
      "reference": "pasta-001",
      "name": "Spaghetti 500g",
      "quantity": 3,
      "shipping_attributes": { "delivery_id": "Shipment-2" }
    }
  ]
}

Selected shipping options, plural

A split-shipping order has more than one selected option, so the Checkout API, the callback API and the Order Management API all expose a selected_shipping_options array, with one entry per selected option and the same structure as the singular field.

The two are mutually exclusive. With exactly one selected option you get selected_shipping_option and no array; with more than one you get the array and no singular field at all — it is omitted, not left holding the first of them. So branch on which of the two is present rather than reading the singular one and hoping.

Related

• Shipping Assistant setup — the general KSA setup this page deviates from
• Shipping partners — the other TMS connectors
• Create the order — where deliveries and merchant_reference1 are set
• Update or cancel an order — reading selected_shipping_option after completion
• Order management — why post-completion updates don’t reach Ingrid