# Create a Delivery
Creates a new delivery in the Rendr platform. Depending on configuration, this can either request a delivery (queued for carrier assignment) or immediately book it with a carrier.
***
## Endpoint
```
POST {{domain}}/{{tenant_id}}/deliveries
```
**Authentication:** Bearer token required via the `Authorization` header.
***
## Request Payload
```json title="POST /{{tenant_id}}/deliveries"
{
"store_reference": "002",
"reference": "myorder-001",
"ready_for_pickup_at": "2026-02-04T11:21:13",
"delivery_type": "standard",
"book_delivery_now": true,
"use_dynamic_RFP": true,
"ignore_buffer_time": true,
"authority_to_leave": true,
"special_instructions": "Deliver to level 3",
"pickup_instructions": "Collect from back office",
"price_cents_total_value": 12000,
"provider_options": {
"provider": "Australia Post",
"service": "EXPRESS POST + SIGNATURE"
},
"address": {
"address": "7 Howard Street",
"address2": "Level 3",
"city": "Richmond",
"state": "VIC",
"post_code": "3121",
"country": "AU"
},
"customer": {
"first_name": "Test",
"last_name": "Rendr",
"email": "greg@rendr.delivery",
"phone": "0400000000",
"country": "AU"
},
"line_items": [
{
"code": "328863",
"name": "XXXXX",
"price_cents": 5900,
"quantity": 1
}
],
"parcels": [
{
"reference": "PARCEL_001",
"length_cm": 40,
"width_cm": 40,
"height_cm": 40,
"weight_kg": 5,
"quantity": 1
}
]
}
```
***
## Parameters
### Top-Level Fields
| Field | Type | Required | Description |
| ------------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store_id` | String | Yes\* | The Rendr store ID for the pickup location. Determines the origin point of the delivery. |
| `store_reference` | String | Yes\* | Your internal location identifier preconfigured by your Rendr implementation partner. Can be used instead of `store_id`. |
| `reference` | String | Yes | Your unique identifier for this delivery — typically an order number from your OMS or POS. Must be unique per store. |
| `ready_for_pickup_at` | String (ISO 8601) | Yes | The earliest date and time the order will be ready for carrier collection. Include any pick/pack buffer time in this value. |
| `delivery_type` | String | No | The service level for this delivery. Accepted values: `fast`, `flexible`, `standard`, `express`. Determines the delivery speed and carrier pool considered. |
| `book_delivery_now` | Boolean | No | When `true`, Rendr immediately attempts to book the delivery with an available carrier rather than queuing it. Use when the order is already packed and ready. Defaults to `false`. |
| `use_dynamic_RFP` | Boolean | No | Enables dynamic ready-for-pickup time calculation. When `true`, Rendr adjusts the pickup time based on real-time carrier availability to improve on-time performance. |
| `ignore_buffer_time` | Boolean | No | When `true`, Rendr bypasses any configured store buffer time when calculating carrier pickup windows. Use with care — intended for scenarios where the order is already prepared ahead of schedule. |
| `authority_to_leave` | Boolean | No | When `true`, the carrier is permitted to leave the parcel unattended if no one is home. Passed to the carrier and displayed on the tracking page. |
| `special_instructions` | String | No | Free-text delivery instructions shown to the driver at the point of delivery — e.g. `"Deliver to level 3"`. |
| `pickup_instructions` | String | No | Instructions for the carrier at pickup, shown when they arrive at the store — e.g. `"Collect from back office"`. |
| `price_cents_total_value` | Number | No | The total declared value of the order in cents — e.g. `12000` = \$120.00 AUD. Used for insurance classification and high-value handling decisions. |
Either `store_id` or `store_reference` must be provided. If both are supplied, `store_id` takes precedence.
### Provider Options
The `provider_options` object allows you to pin the delivery to a specific carrier and service. This is used on BYOC (Bring Your Own Carrier) accounts where you want to override Rendr's automatic carrier selection with a known carrier from a prior quote.
| Field | Type | Required | Description |
| --------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `provider_options.provider` | String | No | The carrier name to use for this delivery — e.g. `Australia Post`. Must match a carrier configured on your account. |
| `provider_options.service` | String | No | The specific carrier service to use — e.g. `EXPRESS POST + SIGNATURE`. Must match a valid service for the specified provider. |
`provider_options` is typically populated using values returned from the [Quote a Delivery](/api-reference/deliveries/quote-a-delivery) endpoint. Supplying an unrecognised provider or service will result in an error.
### Address Fields
The `address` object specifies the delivery destination.
| Field | Type | Required | Description |
| ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address.address` | String | Yes | The street address of the delivery destination — e.g. `7 Howard Street`. Format: `[Street Number] [Street Name] [Street Type]`. |
| `address.address2` | String | No | A secondary address line for unit, apartment, or level information — e.g. `Level 3`. |
| `address.city` | String | Yes | The city, suburb, or town of the delivery address. |
| `address.state` | String | Yes | The abbreviated state or territory — e.g. `VIC`, `NSW`. |
| `address.post_code` | String | Yes | The postcode of the delivery address. |
| `address.country` | String | Yes | The two-letter ISO 3166-1 alpha-2 country code — e.g. `AU`. |
| `address.business` | Boolean | No | Set to `true` if the delivery destination is a business address. Some carriers enforce signature requirements for business deliveries regardless of ATL settings. |
| `address.company_name` | String | No | The name of the company at the delivery address. Required when `business` is `true`. |
### Customer Fields
The `customer` object captures the recipient's details, used for delivery notifications, tracking page personalisation, and identity verification for regulated goods.
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `customer.first_name` | String | Yes | The recipient's first name. |
| `customer.last_name` | String | Yes | The recipient's last name. |
| `customer.phone` | String | Yes | The recipient's mobile number. Used for SMS delivery notifications and driver contact — e.g. `0400000000`. |
| `customer.email` | String | Yes | The recipient's email address. Used to send email notifications and tracking links. |
| `customer.country` | String | No | The recipient's country code in ISO 3166-1 alpha-2 format — e.g. `AU`. |
### Line Items
The `line_items` array describes the individual products in the order. Displayed to store staff during packing, to drivers at pickup, and used for manifest reconciliation.
| Field | Type | Required | Description |
| ----------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `line_items[].code` | String | Yes | The SKU or product code as it exists in your system. |
| `line_items[].name` | String | Yes | The human-readable product name. Displayed to store staff, drivers, and the customer. |
| `line_items[].price_cents` | Number | Yes | The unit price of the item in cents — e.g. `5900` = \$59.00. Used for insured value and high-value item classification. |
| `line_items[].quantity` | Number | Yes | The number of units of this line item in the delivery. |
| `line_items[].packing_instructions` | String | No | Item-level packing instructions for store staff — e.g. `"Keep upright"`, `"Fragile — wrap individually"`. |
### Parcels
The `parcels` array defines the physical packages making up the delivery. Dimensions and weights are used for carrier rate selection and label generation.
| Field | Type | Required | Description |
| ----------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `parcels[].reference` | String | Yes | A unique reference for this parcel — e.g. `PARCEL_001`. Used during packing, scanning, and carrier handoff. |
| `parcels[].description` | String | No | A short description shown in the Workbench portal to help staff identify the package. |
| `parcels[].type` | String | No | The parcel packaging type. Accepted values: `carton`, `crate`, `hanging_bag`, `length`, `pallet`, `satchel`, `skid`. |
| `parcels[].length_cm` | Number | Yes | The length of the parcel in centimetres. |
| `parcels[].width_cm` | Number | Yes | The width of the parcel in centimetres. |
| `parcels[].height_cm` | Number | Yes | The height of the parcel in centimetres. |
| `parcels[].weight_kg` | Number | Yes | The weight of the parcel in kilograms. |
| `parcels[].quantity` | Number | Yes | The number of identical parcels at these dimensions. Use `quantity: 2` rather than duplicating the object. |
Accurate parcel dimensions and weights are required. Carriers use these values to assign the correct service and generate compliant labels. Incorrect measurements may result in surcharges or carrier rejection at pickup.
***
## Sample Response
A successful request returns a `201 Created` with the full delivery object.
```json title="201 Created"
{
"data": {
"id": "Qq1TkY0xXbDWscq99BHe",
"brand_id": "rendr",
"store_reference": "002",
"reference": "myorder-001",
"status": "booked",
"delivery_type": "standard",
"consignment_number": "111JD8503767",
"special_instructions": "Deliver to level 3",
"authority_to_leave": true,
"ready_for_pickup_at": "2026-02-04T11:21:13+11:00",
"from_datetime": "2026-02-04T11:21:13+11:00",
"to_datetime": "2026-02-06T11:21:13+11:00",
"created_at": "2026-02-03T01:25:23.030Z",
"updated_at": "2026-02-03T01:25:30.195Z",
"requested_at": "2026-02-03T01:25:28.562Z",
"booked_at": "2026-02-03T01:25:30.195Z",
"manifest_status": "pending",
"manifest_group": "Express Post",
"price_cents_total_value": 12000,
"auspost_provider": "Australia Post",
"service_code": "EXPRESS POST + SIGNATURE",
"carrier_code": "3K55",
"label_url": "https://static.uat.rendr.delivery/XXXX",
"address": {
"address": "7 Howard Street",
"address2": "Level 3",
"city": "Richmond",
"state": "VIC",
"post_code": "3121",
"country": "AU",
"lat": -37.833074,
"lng": 144.997631
},
"store_location": {
"name": "Rendr HQ",
"lat": -37.832765,
"lng": 144.997217
},
"customer": {
"first_name": "Test",
"last_name": "Rendr",
"phone": "+61400000000",
"email": "greg@rendr.delivery",
"country": "AU"
},
"line_items": [
{
"code": "328863",
"name": "XXXXX",
"price_cents": 5900,
"quantity": 1
}
],
"parcels": [
{
"reference": "PARCEL_001",
"length_cm": 40,
"width_cm": 40,
"height_cm": 40,
"weight_kg": 5,
"quantity": 1,
"article_id": "111JD850376701000961501"
}
],
"additionals": {
"is_residential": true
},
"service_quote": {
"price_cents": 900,
"from_datetime": "2026-02-04T11:21:13+11:00",
"to_datetime": "2026-02-06T11:21:13+11:00"
},
"product_types": {}
}
}
```
### Response Fields
| Field | Type | Description |
| --------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.id` | String | The unique ID assigned by Rendr to this delivery. |
| `data.brand_id` | String | The brand identifier associated with the delivery. |
| `data.store_reference` | String | The store reference as provided in the request. |
| `data.reference` | String | Your order reference as provided in the request. |
| `data.status` | String | The current delivery status. See [Status Lifecycle](/documentation/key-concepts/status-lifecycle). Common initial values are `requested` or `booked`. |
| `data.delivery_type` | String | The service level used for this delivery (`fast`, `flexible`, `standard`, `express`). |
| `data.consignment_number` | String | The carrier consignment number assigned at booking. Used for carrier-side tracking. |
| `data.special_instructions` | String | Delivery instructions for the driver, as provided in the request. |
| `data.authority_to_leave` | Boolean | Whether the carrier is permitted to leave the parcel unattended. |
| `data.ready_for_pickup_at` | String (ISO 8601) | The earliest time the order can be collected from the store. |
| `data.from_datetime` | String (ISO 8601) | The start of the estimated delivery window. |
| `data.to_datetime` | String (ISO 8601) | The end of the estimated delivery window. |
| `data.created_at` | String (ISO 8601) | Timestamp when the delivery record was created in Rendr. |
| `data.updated_at` | String (ISO 8601) | Timestamp of the last update to the delivery record. |
| `data.requested_at` | String (ISO 8601) | Timestamp when the delivery was submitted to the carrier for booking. |
| `data.booked_at` | String (ISO 8601) | Timestamp when the carrier confirmed the booking. |
| `data.manifest_status` | String | The current manifest status for this delivery. Typically `pending` until the carrier manifest is closed. |
| `data.manifest_group` | String | The carrier manifest group this delivery has been assigned to — e.g. `Express Post`. |
| `data.price_cents_total_value` | Number | The total declared value of the order in cents, as provided in the request. |
| `data.auspost_provider` | String | The carrier name used for this delivery — e.g. `Australia Post`. |
| `data.service_code` | String | The carrier service used — e.g. `EXPRESS POST + SIGNATURE`. |
| `data.carrier_code` | String | The internal Rendr carrier service code used for booking. |
| `data.label_url` | String | URL to the generated shipping label PDF. Present once a carrier booking is confirmed. |
| `data.address` | Object | The delivery destination address, echoed from the request. Includes geocoded `lat` and `lng` coordinates resolved by Rendr. |
| `data.store_location` | Object | The name and coordinates of the pickup store associated with the delivery. |
| `data.customer` | Object | The recipient's details as provided in the request. Note that `phone` is returned in E.164 format (e.g. `+61400000000`). |
| `data.line_items` | Array | The line items as provided in the request. |
| `data.parcels` | Array | The parcels as provided in the request. Each parcel includes an `article_id` assigned by the carrier for individual package tracking. |
| `data.additionals.is_residential` | Boolean | Indicates whether Rendr resolved the delivery address as a residential address. Used for carrier routing decisions. |
| `data.service_quote` | Object | The carrier quote applied to this booking, including `price_cents`, `from_datetime`, and `to_datetime`. |
| `data.product_types` | Object | The product type flags for this delivery. Empty (`{}`) if no regulated goods were declared. |