---
title: "Ingrid checkout API options: V1, V2, and Headless"
canonical: "https://ingrid-support.refined.site/space/KB/754155521/Ingrid%20checkout%20API%20options%3A%20V1%2C%20V2%2C%20and%20Headless"
format: markdown
---
Ingrid offers three ways to bring delivery selection into your checkout. They differ in two things that matter: **who builds the interface**, and **which capabilities are available**. This page explains what each option is, so you can tell which one fits your setup.

If you are already on V1 and want to move to V2, see [Migrating from Checkout V1 to V2](https://support.ingrid.com/space/KB/754221057/Migrating+from+Checkout+V1+to+V2).

## The three options at a glance

|  | Checkout V1 (SIW) | Checkout V2 (Delivery Checkout) | Headless API |
| --- | --- | --- | --- |
| **Status** | Legacy | Current | Current |
| **Who builds the delivery UI** | Ingrid, via an embedded widget | Ingrid, via an embedded widget | You do |
| **Integration effort** | Lower | Lower | Higher |
| **Address form** | Not included — you or your payment provider collect the address | Built in, and optional | Not available — you collect the address |
| **Split shipments** | Not supported | Supported, using delivery groups | Supported, using multiple deliveries |
| **Return promise** | Not available | Available, and requires Ingrid Returns | Built in |
| **Delivery add-ons** | Available | Available | Available |
| **API base path** | `/v1/siw/` | `/v1/delivery_checkout/` | `/delivery/v1/sessions` |

## Checkout V1 (SIW)

The original Ingrid checkout integration. Ingrid returns an HTML snippet that you embed, and the widget handles delivery selection for the shopper.

**V1 is legacy** and no longer actively maintained. Existing V1 integrations continue to work and no retirement date has been announced — but V1 receives no new capabilities. The address form, delivery groups, the return promise, and the Ingrid AI features (predictive delivery times and profit-optimized delivery) are all V2 only.

If you are on V1, plan a move to V2 rather than building anything new on it. See [Migrating from Checkout V1 to V2](https://support.ingrid.com/space/KB/754221057/Migrating+from+Checkout+V1+to+V2).

## Checkout V2 (Delivery Checkout)

The current widget-based integration, and the evolution of V1. It embeds the same way, and adds:

- **Ingrid address form** — address collection, validation, autocomplete, and address book, inside the widget
- **Delivery groups** — split shipments and marketplace setups, with addresses and delivery options per group
- **Session pull** — a dedicated endpoint that refreshes delivery promises without changing session state
- **Currency conversion** — for cross-border checkouts
- **Ingrid AI features** — predictive delivery times and profit-optimized delivery
- **Return promise** — return conditions shown in checkout and stored with the order, so the same promise is reused across tracking, returns, and post-purchase emails. This requires Ingrid Returns.

If you want delivery selection working quickly, with a proven interface you do not have to build or maintain, V2 is the option to choose. To move an existing V1 integration across, see [Migrating from Checkout V1 to V2](https://support.ingrid.com/space/KB/754221057/Migrating+from+Checkout+V1+to+V2).

## Headless API

Headless gives you the delivery data and expects you to build the interface. There is no widget and no HTML snippet — you render the delivery categories, options, pickup points, and prices yourself.

It suits retailers who need full design control, or whose storefront architecture is decoupled. In exchange, you take on more: building and maintaining the delivery selection UI, collecting the address yourself, and managing checkout state in your own frontend.

> **Headless is not a standard part of a Checkout purchase.** Using it requires explicit, written permission from Ingrid Sales, so talk to your Ingrid contact before planning an integration around it.

## How to choose

**Choose V2 if** you want the fastest route to a working delivery experience, you would rather not build a delivery selection interface, or the built-in address form, pickup point maps, and delivery time display are useful to you. This suits most retailers.

**Choose Headless if** you need a checkout design the widget cannot produce, your architecture requires a decoupled frontend, or you want delivery options rendered natively inside an existing custom checkout — **and** you have frontend resources to build and maintain that UI.

**If you are on V1**, migrating to V2 is the smaller step: the embedding model is the same, and the work is mostly on the API and response-parsing side. Moving from V1 straight to Headless means building a delivery UI from scratch.

## Technical differences in detail

| Aspect | V1 (SIW) | V2 (Delivery Checkout) | Headless API |
| --- | --- | --- | --- |
| **Frontend** | Widget, via `html_snippet` | Widget, via `html_snippet` | None — you build the UI |
| **Create session** | `POST /v1/siw/session.create` | `POST /v1/delivery_checkout/session.create` | `POST /delivery/v1/sessions` |
| **Update session** | `POST /v1/siw/session.update` | `POST /v1/delivery_checkout/session.update` | `PATCH /delivery/v1/sessions/{session-name}` |
| **Complete session** | `POST /v1/siw/session.complete` | `POST /v1/delivery_checkout/session.complete` | `CompleteSession` |
| **Read session** | `GET session.get` — regenerates delivery promises | `GET session.get` — read-only · `GET session.pull` — refreshes promises | `GetSession` — read-only |
| **Response structure** | `selected_shipping_option` and `result` | `delivery_groups[]` | `delivery_categories[]` containing `delivery_options[]` |
| **Address in response** | `search_address` and `customer` at session root | Inside `delivery_groups[].addresses` | In the session recipient data |
| **Customer data** | `customer` accepted on create and update | `customer` on complete only, and not needed when using the address form | `recipient` with address and contact details, required at create |
| **Widget events** | `data_changed` | `data_changed` and `summary_changed` | None — you manage state yourself |
| **Suspend and resume** | Required during `session.update` | Required during `session.update` | Not applicable |
| **Pickup points** | Rendered by the widget | Rendered by the widget | Raw data returned — distances, opening hours, addresses. You build the UI |
| **Preselection** | Handled by the widget | Handled by the widget | `preselected` field on options — you implement the logic |
| **Request timeouts** | Not specified | Not specified | Create and update: 7s · Complete and get: 3s |

## Related pages

- [Migrating from Checkout V1 to V2](https://support.ingrid.com/space/KB/754221057/Migrating+from+Checkout+V1+to+V2)
- [Ingrid Delivery Checkout](https://support.ingrid.com/space/KB/11501671/Ingrid+Delivery+Checkout)
- [Ingrid Address form](https://support.ingrid.com/space/KB/536150018/Ingrid+Address+form)
- [Checkout implementation](https://support.ingrid.com/space/KB/11501718/Checkout+implementation)
- [How to structure an operationally viable and high-converting checkout with Ingrid Delivery Checkout](https://support.ingrid.com/space/KB/461373442/How+to+structure+an+operationally+viable+and+high-converting+checkout+with+Ingrid+Delivery+Checkout)
- Developer documentation: [Delivery Checkout](https://developer.ingrid.com/delivery_checkout/) · [Headless Checkout](https://developer.ingrid.com/headless_checkout/) · [SIW (legacy)](https://developer.ingrid.com/siw/api/)