Split fulfilment

This guide is for systems integrating directly with the Quiver API using a merchant API key. Split fulfilment means collecting parts of one order from several stores, consolidating its parcels at a Quiver base (MFC), then making one onward customer delivery.

The split API reference documents operations on an existing split group. These are additional delivery API operations, not a request format for creating arbitrary multi-origin bookings.

Availability and booking

Standalone API merchants can book automatic split deliveries through the normal quote and delivery booking endpoints. No connected commerce platform is required. Quiver must first enable split delivery for your merchant, select the receiving MFC and configure its staffed receiving hours.

Supply your own stable order.merchantOrderId, registered product references and the complete basket. Leave the collection address/location unspecified so Quiver can allocate it. A specified collection keeps the booking single-origin. Quiver tries each enabled store first, then two or three stores when no single store holds the basket. Routes, operating hours and the saved customer promise must all remain feasible.

Standalone support is for direct API (MANUAL/CUSTOM) merchants using Quiver-managed inventory checks. Products need inventory-item mappings and stock at enabled merchant-owned stores. Perishable/batch-tracked inventory and a separate external inventory provider are not supported by this booking path. Keep stock current using the existing inventory API. Quiver atomically reserves every source with the tasks and manifest; a shortage rolls back the whole booking. Retrying an identical order reference returns the same booking, while changed contents are rejected. Do not create separately charged store bookings to simulate a split.

Uncollected cancellation releases the source reservation. Actual collection consumes it; a later cancellation does not pretend those goods returned to store. Record actual returns/stock corrections through the audited inventory workflow. The normal registered parcel labels, packing, base receipt and single-charge rules apply to both connected and standalone bookings.

For an existing supported split group, the direct API operations below provide whole-order reads, eligible customer-delivery edits, parcel metadata and group cancellation. They use your merchant's API key without a platform login.

Read the whole order

All examples use https://api.quiver.london and your merchant's x-api-key. Task IDs below are illustrative.

curl 'https://api.quiver.london/task/tasks/12345/split-order' \
  -H 'x-api-key: YOUR_API_KEY'

An ordinary delivery returns {"split":false}. A split order returns:

{
  "split": true,
  "consolidationId": "a-saved-group-identity",
  "taskIds": [12345, 12346],
  "lineItems": [
    {"merchantProductId": "123456789", "quantity": 1},
    {"merchantProductId": "987654321", "quantity": 2}
  ]
}

taskIds lists the contributing store tasks, not the onward customer task. lineItems is the whole allocated store basket, not one store's subset. A store task's delivery destination is the consolidation base. Its completion does not mean the order has reached the customer.

Read GET /task/tasks/{id}/split-customer using any active member task. Its customerTaskId identifies the onward delivery when one exists; an omitted ID means that task has not been created yet. The response also contains the saved customer address, window, timezone and instructions. Use the normal delivery query/read endpoints to inspect individual tasks. Linked-task IDs alone do not establish that a task is a return or that an order is split.

The group shares customer tracking and has one charge owner. Do not infer extra customer orders or charges from the number of store legs. Customer progress and delivery completion must follow the onward customer delivery, not an arbitrary source task. Keep the tracking URL returned by Quiver; do not construct it from the tracking ID or task number.

Change the customer delivery

Use PATCH /task/tasks/{id}/split-customer for the group's customer address, delivery date/window and instructions. It works before and after creation of the onward task, while that customer delivery is still eligible for changes. It does not change a source store's destination away from the MFC.

curl --request PATCH \
  'https://api.quiver.london/task/tasks/12345/split-customer' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  --data '{"date":"2026-11-10","instructions":"Ring the doorbell"}'

The date is local to the response's timezone. Alternatively supply both from and to as RFC 3339 timestamps. Do not combine date with explicit endpoints, or send only one endpoint. A date preserves the existing local window's clock times; route, service, opening-hour and editable-state checks still apply. An omitted field is preserved; "instructions":"" clears instructions. For an address edit, send an address object using the existing address fields (line1, line2, city, postcode, country).

After an edit, re-read GET /task/tasks/{id}/split-customer to confirm the saved customer promise. Your integration must update its own order record and consume the existing delivery webhooks; Quiver does not automatically write to an arbitrary external order-management system. Timeouts are ambiguous: re-read the saved values before retrying.

GET /task/tasks/{id}/split-customer-sync reports connected-provider sync progress where such a connector exists. It is not a general callback or an acknowledgement from your own system, and is not required to read the saved Quiver customer promise.

Change stores or products

Do not PATCH the whole order basket onto one source task: that mixes allocations and can make collections, stock reservations and labels disagree.

Caller-specified source/product revisions are not currently supported by the public API. The allocation-review and revision endpoints in the supplement operate on a saved connected-provider review; they do not accept a caller's replacement basket or source allocations. They currently require Shopify allocation data and must not be used as a generic revision API. Contact Quiver for supported changes to an existing group.

Collected parcels keep their source, contents and identity. Only eligible uncollected allocations may be revised through a supported review workflow. Customer address/date/instruction edits have their separate eligibility rules above and do not change a collected parcel's source or contents.

A cancelled source followed by an unrelated redelivery booking does not automatically add that parcel to the group. A replacement already physically at base requires the reviewed warehouse recovery job: identify/attach it, print the current labels, scan all parcels and verify packing. Changing a label quantity cannot add a parcel or prove physical custody.

Parcel labels and readiness

GET /task/tasks/{id}/parcel-labels returns the registered parcel manifest for that task: each label has number, total, reference and qrCode. This is metadata, not a printable PDF. Use the existing POST /task/tasks:batchDownloadLabels endpoint for printing. Printing records label activity and can synchronize courier snapshots; treat it as a write.

Use the registered parcel count, never an invented quantity. Numbering spans the group, so one store's subset can legitimately include label 2/2 on its own. Store-to-base labels show that leg's base destination. Labels printed from the onward customer task show the customer destination: print those for the onward journey even when the parcel QR identity is retained.

Approved revisions can invalidate old labels and require new QR identities for replacement parcels. Retained collected parcels keep their identities. Always reload the current manifest after a revision and use the complete returned QR token; do not derive it from display numbering or scan only a shared tracking ID.

The metadata's bookingReady and deliveryReady flags are label/manifest state, not dispatch permission or proof of custody. Actual collection/warehouse receipt, packing, current prints/scans and dispatch holds remain independently enforced. Reopening a completed source can hold the onward delivery again. Resolve the missing parcel through the real receive/recovery workflow rather than forcing its status to collected.

Cancellation, permissions and retries

POST /task/tasks/{id}:cancelSplitDelivery requests group cancellation. Cancelling one source is not a substitute for cancelling the group. Physical state can prevent cancellation; follow the returned explanation and recovery state. Never book a replacement split blindly after an uncertain cancellation.

Use only the owning merchant's credential. Whole-group reads, customer edits and reviews require permission for all contributing stores; revision previews and applications also check proposed sources. A task may be hidden when access is insufficient. Do not supply an operator identity or merchant override in the body to bypass those checks.

Some existing endpoints report temporary booking/order-lock contention as HTTP 400 with an explicit retry shortly explanation. Retry those exact contention outcomes with bounded backoff and the same identities, then re-read current state. Do not treat every 400 as retryable. Stock/configuration validation, collected-parcel locks, stale reviews and unsupported revisions need changed inputs or an operational review. Timeouts on writes are ambiguous: inspect the existing booking/application/sync state before attempting the operation again.