Deliveries

Request vs Book

View as Markdown

When you create a delivery with Rendr, there are two modes of operation: Request and Book. Understanding the difference is important for determining when carrier allocation, label generation, and consignment creation happen in your workflow.

Default Behaviour — Request State

By default, a delivery created via the API is placed in a requested state. In this mode:

  • The delivery record is created in Rendr
  • No carrier is allocated immediately
  • No label is generated
  • No consignment number is assigned

This is the recommended approach when your workflow requires store staff to confirm that stock is picked, packed, and ready before a carrier booking is made. The delivery sits in requested state in Rendr until staff verify the order is ready, at which point the separate Book request is made to trigger carrier allocation and label generation.

If you need to explicitly trigger booking yourself — for example, after a staff confirmation step in your workflow — you can send a separate Book request.

Book a Requested Delivery

PATCH {{domain}}/{{tenant_id}}/deliveries/{{delivery_id_or_reference}}/book

Authentication: Bearer token required via the Authorization header.

This call transitions the delivery from requested to booked, triggering carrier allocation, label generation, and consignment creation at that point in time.

Book on Create

If you want the delivery to be fully booked at the moment the Create Delivery call is made — with a label and consignment number returned immediately in the response — set book_delivery_now: true in your request payload.

POST /{{tenant_id}}/deliveries — Book on Create
1{
2    "store_id": "rendr-test",
3    "reference": "myorder-001",
4    "book_delivery_now": true,
5    "ready_for_pickup_at": "2026-02-04T11:21:13+11:00",
6    ...
7}

When book_delivery_now is true:

  • Carrier allocation happens immediately
  • A consignment number is assigned and returned in the response
  • A shipping label is generated and the label_url is populated in the response
  • The delivery status is returned as booked

When using book_delivery_now: true, ensure the order is already packed and ready for collection. Booking triggers carrier-side processes immediately, and amendments after booking may not be possible depending on the carrier.

Comparison

Request (default)Book on Create
book_delivery_nowfalse (or omitted)true
Initial statusrequestedbooked
Label generated immediatelyNoYes
Consignment number assigned immediatelyNoYes
Carrier allocated immediatelyNoYes
Additional Book call requiredYes, if manually triggeringNo

Choosing the Right Approach

Use Request (default) when:

  • Your workflow requires store staff to confirm stock is picked and ready before a carrier is booked
  • You want a delivery record created in Rendr ahead of fulfilment, with booking triggered separately once the order is confirmed ready

Use Book on Create when:

  • Your workflow enforces inventory verification before the Create Delivery call is made — by the time you’re calling the API, stock is already confirmed and ready
  • You need a label generated immediately to attach to the parcel at the point of creation