Ingrid offers a Delivery Platform that lets merchants configure and present tailored delivery options to their customers based on their own shipping rules and carrier setup.
Our partnership with Ingrid allows merchants using Ingrid to surface their available shipping options directly in Kustom Checkout. Ingrid provides Kustom with delivery options — including split-shipment scenarios — based on the rules and carriers the merchant has configured in their Ingrid account.
You can read more about Ingrid at ingrid.com.
This guide is for platform partners and integration engineers connecting Ingrid as the shipping provider behind Kustom Checkout. It covers how to set up the integration, what shipping data is exposed before and after purchase, and how split-shipping changes the order structure.
Ingrid is integrated through Kustom Shipping Assistant (KSA) using the Ingrid Headless Transport Management System (TMS) connector. KSA fetches shipping options from Ingrid during checkout and maps them onto Kustom's order model, so the merchant works with a single, consistent order representation.
For exact request and response details, refer to the linked API reference pages in each section.
A complete Ingrid + Kustom checkout has two cooperating systems:
- 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 TMS connector, requests shipping options from Ingrid, renders them to the buyer, and records the buyer's choice on the order.
The end-to-end flow — order creation, shipping selection, completion, and shipment booking — is illustrated below.
Open the Ingrid integration flow diagram
The rest of this guide is organised around the order lifecycle: setting up the connection, the pre-purchase flow while the order is still checkout_incomplete, the post-purchase flow once the order is complete, and split-shipping for orders fulfilled by more than one shipment.
Setting up the integration is done in two places: Ingrid and Kustom.
Sign up for the Ingrid Merchant Platform (IMP) and configure your carriers, delivery options, and other shipping settings there. See Ingrid's Access to Ingrid Merchant Platform article and the setup guides available within Ingrid.
You will need the following from Ingrid to complete the Kustom setup:
- Your Ingrid Site ID.
- Your Ingrid private key — the plain key, not the base64-encoded variant.
The general Shipping Assistant setup is documented in How to Set Up Shipping Assistant in Kustom Checkout. Follow that guide, with the following Ingrid-specific details.
Preparation. The general guide's note on digital products does not apply to the Ingrid integration — digital products are handled on Ingrid's side by tagging them with a digital tag rather than through Kustom configuration. You can skip the digital-products step when integrating Ingrid.
Shipping credentials. When activating KSA in the Kustom Portal, configure the connection as follows:
| Field | Value |
|---|---|
| TMS | Select Ingrid Headless. Available in both Playground and Production. |
| Identifier | Your Ingrid Site ID. |
| Key | Your Ingrid private key — the plain key, not base64-encoded. |
In Playground, the Ingrid Headless TMS connects to Ingrid's staging environment; in Production, it connects to Ingrid's production environment.
The remaining setup steps — activating KSA in the Portal, triggering KSA in the checkout payload, and verifying the setup in Playground — are unchanged from the general Shipping Assistant guide.
Some merchants currently run a dual-iframe checkout during a transition period — an Ingrid iframe on top and a Kustom iframe below. Such merchants may need to keep collecting a separate shipping address while not yet showing shipping options sourced from Ingrid inside Kustom.
To suppress option fetching, pass options.tms_configuration_override.disabled as true when creating the order. Kustom will then collect the address but will not fetch shipping options from Ingrid.
The pre-purchase flow covers everything after the order is created but before it is completed — that is, while the order's status is checkout_incomplete.
The selected_shipping_option attribute — present both in the order response and in callbacks — describes the shipping option the buyer chose. Its fields are populated from Ingrid as follows:
| Field | Mapped from |
|---|---|
id | The shipping option ID generated by Ingrid |
name | The display_name of the Ingrid delivery_category |
description | Not provided |
promo | Not provided |
price | The price of the Ingrid delivery_option |
preselected | Not provided |
tax_rate | Defaults to 25% — see Tax calculation on shipping options |
tax_amount | Calculated from the defaulted 25% tax_rate |
shipping_method | KSA's representation of Ingrid's delivery type and location type — see the table below |
tms_reference | Ingrid's session ID |
tos_id | Available post-purchase only |
shipping_method is derived from Ingrid's delivery_type and, where available, location_type:
| Ingrid delivery type | Ingrid location type | KSA shipping_method |
|---|---|---|
| — | LOCATION_TYPE_UNSPECIFIED | Undefined |
| — | LOCKER | PickUpPoint |
| — | STORE | PickUpPoint |
| — | POSTOFFICE | PickUpPoint |
| — | MANNED | PickUpPoint |
DELIVERY_TYPE_UNSPECIFIED | — | Undefined |
DELIVERY | — | Home |
MAILBOX | — | Postal |
PICKUP | — | PickUpPoint, or Home if no locations are available |
INSTORE | — | PickUpStore, or Home if no locations are available |
selected_shipping_option.delivery_details carries the carrier and logistics detail:
carrier— KSA's supported carrier, decoded from Ingrid's carrier nameclass— alwaysSTANDARDproductidentifier— Ingrid's carrier product IDname— Ingrid's carrier name
timeslotid— Ingrid's generated shipping option ID for the timeslotstart— timeslot start timeend— timeslot end time
pickup_locationid— the numeric ID of the location, as per Ingridname— the name of the locationaddress— the address of the location
selected_shipping_option.selected_addons is an array, with one entry per chosen addon:
type— Ingrid's ID of the addonprice— the price of the addonexternal_id— theexternal_idof the addon as defined in Ingrid
Ingrid does not calculate tax, so KSA defaults tax_rate on the selected shipping option to 25% (and derives tax_amount from it). To avoid overpaying tax, merchants and platforms should apply the correct tax for the shipping option based on the cart.
To do this, implement the shipping option update callback and return one or more shipping_fee order lines on the order in the callback response. These override the defaulted tax_rate and tax_amount.
The merchant's order references — merchant_reference1 and merchant_reference2 — are propagated to Ingrid so that orders can be found easily in the Ingrid Merchant Platform.
⚠️ Important — send merchant references before completion.
- Provide the merchant references before the order is completed so that they can be sent to Ingrid.
- If they are missing at completion time, Kustom passes its own
order_idas theexternal_idof the Ingrid session instead.
- If they are missing at completion time, Kustom passes its own
- Kustom does not update the Ingrid session after the order is completed. Sending merchant references to the Order Management API afterwards will therefore not propagate them to Ingrid.
The post-purchase flow covers the order once it is complete, including retrieving shipping information and booking the shipment with Ingrid.
Shipping information remains available after the order is complete. Both tms_reference and tos_id are found on the selected_shipping_option, in the Checkout API and the Order Management API alike.
The tos_id is usually all that is needed to book a shipment, since Ingrid auto-fills the remaining information. If another system needs more detail, the tos_id can be used to fetch the full shipment information from Ingrid via the sessions_summaries.list API.
Because the Ingrid Headless API shares much of its model with the Ingrid delivery checkout API, the tos_id is enough for Ingrid to have all the information required to create a shipment.
To fulfil the order, the merchant creates and books the shipment with Ingrid using Ingrid's SOM API, providing the tos_id from the order's selected_shipping_option.
A single order can be fulfilled by more than one shipment. For example, when goods come from multiple warehouses, or need to be shipped separately for any other reason, split-shipping is the way to model that.
The split-shipping flow is illustrated in the split-shipping flow diagram.
The pre-purchase and post-purchase flows are nearly identical for split-shipping. The differences are in how the order is set up and in the structure of the selected shipping options.
Deliveries
The deliveries array holds information about each shipment. Every order line — except lines of type gift_card and store_credit — must be assigned to a delivery via order_lines[].shipping_attributes.delivery_id.
{
...
"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" }
}
]
}
...
}There is no enforced limit on the number of deliveries an order can have.
Selected shipping options
A split-shipping order naturally has more than one selected shipping option. The Checkout API, the callback API, and the Order Management API therefore expose an additional selected_shipping_options attribute: an array whose entries have the same structure as selected_shipping_option, one per selected shipping option.