---
id: ingrid
title: Ingrid Adapter
hide_title: true
description: "How to use Ingrid with Walley Checkout"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Ingress from "../../../src/components/ingress/ingress.react";
import IngridInitCheckout from "./examples/ingrid-json-example-init-checkout.mdx";
import IngridUpdateCheckout from "./examples/ingrid-json-example-update-checkout.mdx";
import IngridUpdateCart from "./examples/ingrid-json-example-update-cart.mdx";
import IngridGetCheckout from "./examples/ingrid-json-example-get-checkout.mdx";

<Ingress title="Ingrid Adapter">
    Ingrid Delivery Platform, which can be used to power Walley Checkout, connects retailers, carriers and consumers to create a better shopping experience for everyone.
</Ingress>

<center>
  <img src="/img/logos/ingrid-logo.svg" alt="" width="30%" />
</center>

## How to get started 🚀

1. Contact [Walley Merchant Services](/support) for help with setup in our test environment and for questions regarding integration Ingrid.
2. If you do not have one already, then create an account with Ingrid
3. Provide Walley Merchant Services with Ingrid API key as well as what [fallback strategy](./introduction-delivery-module#fallback-strategy-and-shipping-fees) to use.

## Ingrid links


    <a href="https://www.ingrid.com/" target="_blank">Ingrid</a>
    <br/>
    <a href="https://developer.ingrid.com/" target="_blank">Ingrid developer documentation</a>
    <br/>
    <a href="https://support.ingrid.com/walley" target="_blank">Ingrid support documentation for Walley Integration</a>

## Loyalty booster synergies
If you are using any of our loyalty boosters, we forward the customer's membership to Ingrid as the cart attribute `loyalty-isMember`, set to one of `Yes`, `No` or `New` — for example `loyalty-isMember=Yes`:
* Yes: The customer is an existing member.
* No: The customer is not a member and has opted out of becoming one.
* New: The customer is not a member but has opted in to become one.

Does your loyalty program use membership levels? Then we also send an existing member's level as the cart attribute `loyalty-level=<levelName>`, for example `loyalty-level=Gold` — the name exactly as you wrote it, and the same level your customer sees in the checkout. No levels, or no level for that member, means no attribute.

Use it to price shipping by level in Ingrid: free home delivery for your top level, a reduced fee for the one below.

## Extending regular Walley API requests

Walley checkout with Ingrid might require more information than a regular walley checkout. Below are examples of how to extend the regular Walley API requests to include the necessary information for Ingrid.

<Tabs queryString="tab" defaultValue="init" values={[
{ label: 'Initilize checkout', value: 'init' },
{ label: 'Update checkout', value: 'update' },
{ label: 'Update cart', value: 'update-cart' },
]}>

<TabItem value="init">
<IngridInitCheckout />
</TabItem>

<TabItem value="update">
<IngridUpdateCheckout />
</TabItem>

<TabItem value="update-cart">
:::info Important
This only updates shipping information at the cart level — you cannot change global shipping properties with this endpoint.
This can lead to conflicts when using split-shipping since a shipment might refer to a specific cart item. If you use split-shipment, use the Update Checkout operation instead.
:::

<IngridUpdateCart />
</TabItem>

</Tabs>

### Walley ⇨ Ingrid data mapping

| Walley checkout cart items properties                               | Ingrid request properties                                  |
| ------------------------------------------------------------------- | ---------------------------------------------------------- |
| id                                                                  | cart.items.sku (if sku is not present)                     |
| description                                                         | cart.items.name                                            |
| unitPrice                                                           | cart.items.price                                           |
| quantity                                                            | cart.items.quantity                                        |
| sku                                                                 | cart.items.sku                                             |
| shipping.tags                                                       | cart.items.attributes                                      |
| shipping.unitWeight                                                 | cart.items.weight                                          |
| shipping.dimensions                                                 | cart.items.dimensions                                      |
| shipping.shippingInterval.startDate                                 | cart.items.shipping_date.start                             |
| shipping.shippingInterval.endDate                                   | cart.items.shipping_date.end                               |
| shipping.shippingInterval.alternatives[].name                       | cart.items.shipping_date.category_tags.name                |
| shipping.shippingInterval.alternatives[].shippingInterval.startDate | cart.items.shipping_date.category_tags.shipping_data.start |
| shipping.shippingInterval.alternatives[].shippingInterval.endDate   | cart.items.shipping_date.category_tags.shipping_data.end   |

| Walley checkout shipping properties                        | Ingrid request properties                            |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| tags                                                       | cart.attributes                                      |
| shipments[].tags                                           | cart.groups.attributes                               |
| shipments[].id                                             | cart.groups.group_id                                 |
| shipments[].contents[].sku                                 | cart.groups.contents.sku                             |
| shipments[].contents[].quantity                            | cart.groups.contents.quantity                        |
| shippingInterval.startDate                                 | cart.shipping_data.start                             |
| shippingInterval.endDate                                   | cart.shipping_data.end                               |
| shippingInterval.alternatives[].name                       | cart.shipping_date.category_tags.name                |
| shippingInterval.alternatives[].shippingInterval.startDate | cart.shipping_date.category_tags.shipping_data.start |
| shippingInterval.alternatives[].shippingInterval.endDate   | cart.shipping_date.category_tags.shipping_data.end   |

## Extending regular Walley API GET checkout response

As with any delivery adapter walley provide information about the selected delivery when you [get checkout information](/docs/checkout/getcheckoutinformation) located in the `shipping` property.
When using the Ingrid Adapter you will get additional data that you can find in the mapping tables below.


### Walley provided shipping data

| Walley checkout properties             | Walley provided values       |
| ---------------------------------------| --------------------------------------------------------------------------------------------------------------------------- |
| shipping.provider                      | 'Ingrid' or 'MerchantFallback'                                                                                              |
| shipping.shippingFee                   | Total cost of all deliveries                                                                                                |
| shipping.externalSessionId             | The Ingrid session id. Returned once the purchase is completed, so you can fetch the remaining delivery data from Ingrid.    |
| shipping.shipments[]                   | All of the data in each shipment (except feeItemId) is taken from the Ingrid session, and can be found in the table below.  |
| shipping.shipments[].feeItemId         | Id for the shipping fee item                                                                                                |

### Ingrid ⇨ Walley data mapping
| Walley checkout shipment properties (found in shipping.shipments[]) | Ingrid delivery group properties (found in session.delivery_groups[])                                        
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------
| id                                                                   | group_id                                          
| externalShipmentId                                                   | tos_id                                            
| metadata.customerDeliveryPromise.earliest                            | delivery_time.customer_delivery_promise.earliest  
| metadata.customerDeliveryPromise.latest                              | delivery_time.customer_delivery_promise.latest    
| metadata.carrierDeliveryPromise.earliest                             | delivery_time.carrier_delivery_promise.earliest   
| metadata.carrierDeliveryPromise.latest                               | delivery_time.carrier_delivery_promise.latest     
| metadata.pickupFromMerchant.earliest                                 | delivery_time.pickup_from_merchant.earliest       
| metadata.pickupFromMerchant.latest                                   | delivery_time.pickup_from_merchant.latest         
| shippingChoice.id                                                    | shipping.carrier_product_id                       
| shippingChoice.name                                                  | category.presented_category_name (falls back to category.name, then shipping.carrier)
| shippingChoice.carrier                                               | shipping.carrier                                  
| shippingChoice.product                                               | shipping.product                                  
| shippingChoice.fee                                                   | pricing.price / 100                               
| shippingChoice.metadata                                              | shipping.meta                                     
| shippingChoice.destination.id                                        | address.location.external_id                      
| shippingChoice.destination.name                                      | address.location.name                             
| shippingChoice.destination.metadata.address.addressLines             | address.location.address.addressLines             
| shippingChoice.destination.metadata.address.apartmentNumber          | address.location.address.apartmentNumber          
| shippingChoice.destination.metadata.address.attn                     | address.location.address.attn                     
| shippingChoice.destination.metadata.address.careOf                   | address.location.address.careOf                   
| shippingChoice.destination.metadata.address.city                     | address.location.address.city                     
| shippingChoice.destination.metadata.address.companyName              | address.location.address.companyName              
| shippingChoice.destination.metadata.address.country                  | address.location.address.country                  
| shippingChoice.destination.metadata.address.firstName                | address.location.address.firstName                
| shippingChoice.destination.metadata.address.lastName                 | address.location.address.lastName                 
| shippingChoice.destination.metadata.address.postalCode               | address.location.address.postalCode               
| shippingChoice.destination.metadata.address.region                   | address.location.address.region                   
| shippingChoice.destination.metadata.address.street                   | address.location.address.street                   
| shippingChoice.destination.metadata.address.streetNumber             | address.location.address.streetNumber             
| shippingChoice.options[].id                                          | shipping.delivery_addons[].id                     
| shippingChoice.options[].value                                       | shipping.delivery_addons[].external_addon_id      
| shippingChoice.options[].fee                                         | shipping.pricing.price_components[].value         

### Total shipping fee per shipment

There is no single property that holds the total shipping cost for a shipment. When using split shipping you calculate the
total fee for each shipment in `shipping.shipments[]` by summing the fees of the selected delivery:

```
shippingChoice.fee + shippingChoice.destination.fee + shippingChoice.destination.deliveryDate.fee + sum(shippingChoice.options[].fee)
```

:::note
Properties that are not part of the selected delivery are omitted or `null`, and should be treated as `0` in the calculation.
:::

The sum of the total fee of all shipments equals `shipping.shippingFee`.

### Example

<IngridGetCheckout />