Order bundling

In Sparqle, every order is exactly one physical parcel (a collo). When a single shipment needs to travel as more than one parcel, you create one order per parcel and group them into a delivery bundle. The bundle keeps the parcels together through routing and lets you fetch all their labels in a single call. Each order in a bundle keeps its own orderRef, dimensions, and weight — bundling doesn’t merge them, it links them.

How bundling works

You bundle orders by referencing a shared bundle on create. The first order creates the bundle; every following order joins it by passing its bundleId as orderBundleId.

Create the first order without a bundle

Call POST /orders as usual, leaving orderBundleId out. The response includes an orderBundle object — note its bundleId.

Create the next orders with orderBundleId

Call POST /orders again for each additional parcel, this time passing the bundleId from the first response as orderBundleId. Each order joins the same bundle.

Fetch the labels together

Retrieve every label in the bundle at once with GET /orders/label/bundle/{orderBundleId}. See Labels.

1. Create the first order

Leave orderBundleId out. Sparqle creates a new bundle and returns it as orderBundle:

{
  "orderId": "SPQ-10293",
  "orderRef": "PADE3JWEA-1",
  "status": "draft",
  "barcode": "3STBXX123456789",
  "orderBundle": {
    "id": 7419,
    "bundleId": "VNN1UY7TMSY81P8Q4A2C7"
  }
}

2. Create the next orders in the bundle

Use the bundleId from the first response as orderBundleId on every additional parcel. Give each order its own orderRef and its own dimensions:

curl -X POST https://staging-v2.sparqle.tech/orders \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ABC123",
    "orderRef": "PADE3JWEA-2",
    "orderBundleId": "VNN1UY7TMSY81P8Q4A2C7",
    "deliveryName": "Jane Doe",
    "deliveryEmail": "[email protected]",
    "deliveryPhone": "+31612345678",
    "deliveryAddress": {
      "street": "Gustav Mahlerlaan",
      "houseNumber": "320",
      "postalCode": "1082 ME",
      "city": "Amsterdam",
      "countryCode": "NL"
    }
  }'

Repeat for each remaining parcel, reusing the same orderBundleId.

orderBundleId is the bundle’s bundleId (the string), not its numeric id. Only pass it on orders that join an existing bundle — never on the first order, which creates the bundle.

Fetch all labels for a bundle in one request with GET /orders/label/bundle/{orderBundleId}, and print them in a single pass.

Get started

Core concepts

Guides

How bundling works

1. Create the first order

2. Create the next orders in the bundle

​How bundling works

​1. Create the first order

​2. Create the next orders in the bundle

How bundling works

1. Create the first order

2. Create the next orders in the bundle