--- title: "Headless checkout API migration – Shopify App" canonical: "https://ingrid-support.refined.site/space/KB/448954369/Headless%20checkout%20API%20migration%20%E2%80%93%20Shopify%20App" format: markdown --- ## Overview On 2/20/2026 Ingrid released a fundamental update to the Shopify Checkout app that improves reliability, speed and enables next step development. Stores that installed the Ingrid checkout app before this release are currently using the legacy internal API (COS v1), which Ingrid plans to sunset. Stores installed after the release are automatically enrolled in the Headless API. This update improves performance, logging, and enables a range of upcoming features. The deadline for this migration is 2026-12-31. --- # Section 1: For Technical Roles ## Why This Matters The migration to the Headless API introduces: - A new backend API endpoint - Changes to the `shipping_lines[].code` format - A new session data structure - Updated completed shipping data format - Improved logging for easier debugging If you are: - Fetching session data programmatically - Parsing the shipping line code - Extracting Ingrid session data into downstream systems (e.g. WMS, ERP) You **must validate compatibility before enabling**. --- ## Technical Changes ### 1. New API The Shopify app now uses: [https://developer.ingrid.com/headless_checkout/backend/](https://developer.ingrid.com/headless_checkout/backend/) If you fetch session data using a session ID, you must switch to the Headless API: **Get Session endpoint:** [https://api.ingrid.com/delivery/v1/_/swagger/#/DeliveryService/DeliveryService_GetSession](https://api.ingrid.com/delivery/v1/_/swagger/#/DeliveryService/DeliveryService_GetSession) Any downstream systems (WMS, middleware, ERP integrations) must use this endpoint. --- ### 2. Shipping Line Code Format Change The value stored in `order.shipping_lines[].code` has changed. ### Old Format (COS v1) `ingrid[session_id][internal_shipping_method_id][price_minor_units][type]` Example: `ingrid[b5e65651-b429-41f1-ad8f-6db1298c6ae1][budbee-box][0][pickup]` ### New Format (Headless API) `ingrid[session_id][delivery_category_id|internal_shipping_method_id][price_minor_units][type]` Example: `ingrid[VM2-511da702662a4c2b92a2674bdcea3089][dhl-pickup-5857dc86a5a84b6d80018d74c7314ea6|dhl-svp][500][pickup]` If you parse this field, ensure your logic supports: - The pipe (`|`) separator - Delivery category ID - Updated session format If you are using the app setting **“Use external method id as shipping code”**, no changes apply. --- ### 3. Completed Shipping Data Field The “Ingrid complete session data” field in Shopify orders now uses the **Headless API session format**. If your system: - Parses JSON from this field - Maps shipping data downstream You must validate compatibility. --- ## How to Verify You’re on Headless API 1. Log into: [https://mad-stage.ingrid.com/](https://mad-stage.ingrid.com/) 2. Go to **Transport Orders** 3. Check the **Source** column If it says **“Headless Checkout”**, you are migrated. --- ## Technical Migration Checklist Before enabling in production: - [ ] Switch to the Headless API Get Session endpoint, if used - [ ] Update parsing logic for `shipping_lines[].code` , if used - [ ] Validate handling of the updated complete session data field, if used - [ ] Perform end-to-end testing in a staging/test store (If you don’t have a staging store set up you can follow Shopify’s guide on [how to set up a dev store](https://shopify.dev/docs/apps/build/dev-dashboard/development-stores) and then install the Ingrid app. You’ll automatically be enrolled on the headless API in the new store. --- # Section 2: For Commercial Roles ## Why This Migration Is Important The Ingrid Shopify Checkout Application’s core has been updated to a better integration to the Ingrid Checkout service. This is an important step in order to provide better quality, stability and development speed. ## What the Migration Unlocks ### Performance & Stability - Improved performance - Better logging → faster support resolution - Reduced debugging time ### New & Upcoming Features The migration is required for several new and upcoming features: - Delivery category and time rework (Released on 7/21/2026) - Improved delivery time estimates shown in checkout - Localized presentation based on checkout page locale - Flexible delivery date formats: - Date - Days - Time units: - Days - Business days - Weeks - Hours - Minutes - Time slots (if supported by carrier) - Timespan-based estimates - Custom delivery text (fully override Delivery time estimates) - Custom labels (e.g., Express, Sustainability, Swan-label, Custom labels) - Label color (hex) - Icons (curated Phosphor icon set) - Toggle to keep completed session data off orders — global setting to stop saving Ingrid session details onto Shopify orders - B2B orders carry a `b2b` cart attribute into the Ingrid session (new input for delivery rules) - Rate bundling — same-price carrier options bundle into one choice by default; multi-product rates named after their carrier product - DHL Packstation UI support — customer number field, persisted on the order as a note attribute - Improved stability on order completion towards Ingrid - See our exciting Shopify roadmap in the [product roadmap](https://www.ingrid.com/products/roadmap) Without migrating, these features are not available. --- ## Who Needs to Take Action? If your store had the Ingrid Delivery Checkout app before the release on 2026-02-20, you must request enrollment on the new API. If the app was installed after the release date, you are automatically enrolled. --- ## Enrollment Process 1. Reach out to your CSM or **[contact support](https://ingrid-ab.atlassian.net/servicedesk/customer/portal/1)** 2. Include your `.myshopify.com` URL(s) (including your dev/staging store) 3. Wait for a reply confirming the headless API has been enabled 4. Test an order end-to-end from order placement to booking a label in a staging/test store 5. Schedule go-live date with Ingrid 6. Monitor post-activation and get in contact if any issues occur