Delivery Groups

Delivery Checkout API supports split shipments for merchants. Additionally, it can serve marketplace platforms (also ones with per vendor configurations). Both mentioned use cases can be materialised with use of groups. Group is a set of items that can differ from other groups by having different field value or condition met, like different shipping dates.

Delivery Group concept is flexible enough to handle a myriad of situations, like shipping items from different warehouses, stores or applying custom splitting logic on integrator side to group items into sets.

If you don't want to use neither split shipment nor you are a marketplace, your integration needs to handle only one group.

Configuring split shipment logic

Splitting logic of cart items into delivery groups can be done manually by integrator. Splitting is done over the cart items based on the previously defined condition during session create and updates.

Each group will be mapped to a separate order.

Handling the split shipments manually

Splitting cart items into delivery groups can be handled manually by the integrator. In order to perform the splitting, one has to define the cart.groups field in create/update session requests to Delivery Checkout API. This powerful feature is a great fit for integrators wanting to have full control over the delivery groups and split shipments or wanting to keep the split shipment logic on their side.

Example create session request with cart items split into delivery groups can look as follows.

{
  "cart": {
    "cart_id": "cart-identifier",
    "items": [
      {
        "sku": "sku-1",
        "name": "Item name 1",
        "price": 900,
        "quantity": 2
      },
      {
        "sku": "sku-2",
        "name": "Item name 2",
        "price": 100,
        "quantity": 2
      }
    ],
    "groups": [
      {
        "group_id": "group-1",
        "header": "Delivery 1",
        "attributes": ["attribute 1", "attribute 2"],
        "contents": [{ "sku": "sku-1", "quantity": 1 }]
      },
      {
        "group_id": "group-2",
        "header": "Delivery 2",
        "attributes": ["attribute 1"],
        "contents": [
          { "sku": "sku-1", "quantity": 1 },
          { "sku": "sku-2", "quantity": 2 }
        ]
      }
    ],
    "total_value": 2000
  },
  "locales": ["en-US"],
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  "search_address": {
    "country": "SE",
    "postal_code": "11151"
  }
}

There are some assumptions, that should be kept in mind when using the split feature:

• when cart.groups field is provided in the request, each group defined in the request should have group_id and contents defined,
• when cart.groups field is provided in the request, all cart items should be mapped to the delivery groups,
• groups cannot have the same group IDs,
• cart items are assigned to the groups by SKU and quantity.

Manual Split with Duplicate SKUs

It is possible to include multiple items with the same SKU in the cart. This can be useful, for example, when you want to display a discounted item on a separate line for campaigns like "Buy 2, Get 1 Free."

When performing a manual split based on delivery groups in such cases, items will be distributed into delivery groups in the order they appear in the cart. For instance, if a customer places 3 t-shirts in the cart, with 2 appearing on the first line as regular items and the 3rd appearing on the second line as a discounted item, and you request 2 delivery groups where the first group has 1 t-shirt and the second group has 2 t-shirts, the distribution will be as follows:

1. The first delivery group will include 1 of the non-discounted t-shirts from the first line.
2. The second delivery group will include the remaining non-discounted t-shirt from the first line and the discounted t-shirt from the second line.

If your use case requires more control, there are two options available:

• Use unique SKUs.
• Adjust the order in which items appear in the cart to achieve the desired split.