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
General split booking for standalone API integrations is not currently
supported. The existing automatic booking implementation depends on a
connected Shopify merchant, its order/variant identities and its allocation
state. These are implementation prerequisites, not instructions to use Shopify
as the integration interface. A standalone API client cannot currently submit
its own collection allocations or enable splitting with a request flag.
Ask Quiver to confirm support for your merchant before implementing this flow.
Continue using the ordinary quote and delivery booking endpoints for supported
single-origin deliveries. Use your own stable order reference in
order.merchantOrderId and your registered product references in
merchantProductId; do not substitute another platform's identifiers or create
separately charged store bookings to simulate a split order.
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.