# New Booking
## Request delivery
`POST` `{baseUrl}/deliveries`
To create a new delivery booking, provide the following details:
1. **Pick-up Details**\
Include the necessary pick-up information such as address, contact person etc.
2. **Drop-off Details**\
Include drop-off information such as address, contact person etc.
3. **Optional Customer Contact**\
You can specify a customer by including `bookingName` and either:
* **bookingEmail**: The customer's email address.
* **bookingPhone**: The customer's phone number.
> **Note**: If neither field is provided, the delivery will not be associated with a customer.
>
> **`bookingName`** is optional but can be included to specify the customer's name.
4. **Order Type**\
Set the `orderType` to `PROCESSING`. This ensures that the delivery will be handled by your partners.
5. **Optional Partner Assignment**\
You can assign the delivery to a specific partner at the time of booking by using the `assignedPartner` field on the drop object. Provide the partner's ID, which can be obtained from the [**Get Delivery Price Estimate**](https://docs.sendstackhq.com/delivery-api/estimates/get-delivery-price) request.
6. **Optional custom fields**
You can include any custom fields configured via the dashboard directly within the `pickup` and `drop` objects.
These fields are useful for capturing additional, business-specific information during booking.
For example:\
If you've added custom fields in the dashboard like:
* `pickup_house_number` on the pickup form
* `dropoff_house_number` on the dropoff form
You can include them in your booking via the `pickup` and `drop` objects respectively as shown on the sample payload below.
#### Headers
| Name | Type | Description |
|---|
| app_id* | String | |
| app_secret* | String | |
#### Request Body
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------------------------- |
| pickup\* | object | Pickup details |
| drops\* | array | Dropoff locations and details |
| orderType\* | string | |
| bookingName | string | specifies the name of the customer |
| bookingPhone | string | specifies phone number of customer |
| bookingEmail | string | specifies email of customer |
**pickup object**
| Field | Description | Data Type | Constraints |
| --------------- | -------------------------------------------------------------------------------------------------------- | --------- | ----------- |
| long | Longitude of specified pickup address | Number | Optional |
| lat | Latitude of specified pickup address | Number | Optional |
| locationCode | Maps to an area, local government, or province connected to the address | String | Optional |
| city | Pickup city | String | Optional |
| state | Pickup state | String | Optional |
| country | Pickup country | String | Optional |
| address2 | Address line 2 | String | Optional |
| address | Pickup address | String | Required |
| pickupName | Pickup name | String | Required |
| pickupEmail | Pickup email | String | Optional |
| pickupNumber | Pickup phone number | String | Required |
| altPickupNumber | Alternative pickup phone number | String | Optional |
| postalCode | Pickup address postal code | String | Optional |
| note | Pickup note | String | Optional |
| pickupDate | The date scheduled for the pickup | String | Optional |
| pickupOtp | Preferred pickup otp to be used. If not specified, a delivery pickup otp will be automatically generated | String | Optional |
#### Drop Object
| Field | Description | Data Type | Constraints |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------- |
| long | Longitude of the drop-off address | Number | Optional |
| lat | Latitude of the drop-off address | Number | Optional |
| locationCode | Maps to a specific area or region connected to the address | String | Optional |
| city | Drop-off city | String | Optional |
| state | Drop-off state | String | Optional |
| country | Drop-off country | String | Default: "NG" |
| address | Drop-off address | String | Required |
| address2 | Address line 2 | String | Optional |
| recipientName | Recipient’s name | String | Required |
| recipientNumber | Recipient’s phone number | String | Required |
| recipientEmail | Recipient’s email address | String | Optional |
| altRecipientNumber | Alternative recipient phone number | String | Optional |
| express | Indicates if express delivery is requested | Boolean | Optional |
| category | Delivery category | String | Optional |
| note | Additional delivery notes | String | Optional |
| value | Value of the item being delivered | Number | Optional |
| description | Description of the item | String | Optional |
| height | Height of the package (cm) | Number | Optional |
| length | Length of the package (cm) | Number | Optional |
| width | Width of the package (cm) | Number | Optional |
| weight | Weight of the package (kg) | Number | Optional |
| assignedPartner | ID of the assigned partner | String | Optional |
| postalCode | Drop-off address postal code | String | Optional |
| categoryId | ID of the delivery category | String | Optional |
| podAmount | Pay on delivery amount | Number | Optional |
| amount | Delivery amount. If provided, it will override the default calculated amount for the delivery | Number | Optional |
| partnerFee | Fee charged by the partner | Number | Optional |
| estimatedPickupWindow | Estimated pickup time window (date and time range).
If provided, it will override the default pickup window for the delivery
| Object | Optional (start, end) |
| estimatedDropoffWindow | Estimated drop-off time window (date and time range). If provided, it will override the default drop-off window for the delivery | Object | Optional (start, end) |
| externalOrderId | External order id | String | Optional |
| dropoffOtp | Preferred dropoff otp to be used. If not specified, a delivery dropoff otp will be automatically generated | String | Optional |
{% tabs %}
{% tab title="200 Request successfully placed" %}
```
{
id: '65fbe637eadabd3da02c3143',
trackingUrl: 'https://app.sendstack.africa/tracking?batchId=R8XB5B',
paymentStatus: 'PAID',
paymentSource: 'self',
batchId: 'R8XB5B',
totalAmount: 1500,
initiator: '65fbe629eadabd3da02c2fab',
pickup: {
address: '1894 Walker Motorway',
pickupName: 'Ramona Rowe',
pickupNumber: '+2349092264624',
pickupDate: '2024-03-22T00:00:00.000Z',
lga: 'Location 1',
state: 'Lagos'
},
drops: [
{
id: '65fbe637eadabd3da02c3141',
fulfillmentPartner: 'Sendstack',
podPaymentStatus: 'PENDING',
status: 'ASSIGNED',
trackingId: 'S1ZZ4U',
trackingUrl: 'https://app.sendstack.africa/tracking?trackingId=S1ZZ4U',
batchId: 'R8XB5B',
address: '2501 Smitham Junctions',
recipientName: 'Melinda King',
recipientNumber: '+2348099793911',
//...truncated for brevity
}
]
}
```
{% endtab %}
{% tab title="400: Bad Request {{field}} is required" %}
```
{
"status": false,
"message": "Invalid app_id or app_secret",
"data": {
"statusCode": 401,
"message": "Invalid app_id or app_secret",
"isOperational": true,
}
}
```
{% endtab %}
{% tab title="422: Unprocessable Entity Low wallet balance" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
```
// Sample Request information
Url: https://sandbox.sendstack.africa/api/v1/deliveries
method: POST
Headers:
- app_id: "your app_id"
- app_secret: "your app_secret"
```
### Sample Success Data
```json
//Sample Request Body
{
"orderType": "PROCESSING",
"bookingEmail": "test@gmail.com",
"bookingName": "test",
"pickup": {
"address": "928 Lowe Lakes",
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"altPickupNumber": "+2348015020200",
"pickupDate": "2024-12-04",
"lat": 6.602928,
"long": 3.345006,
"pickup_house_number": 1 //custom field
},
"drops": [
{
"address": "419 Graham View",
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"altRecipientNumber": "+2348002722212",
"lat": 6.602928,
"long": 3.345006,
"estimatedPickupWindow": {
"start": "2024-12-04T06:00:00.00Z",
"end": "2024-12-04T12:00:00.00Z"
},
"estimatedDropoffWindow": {
"start": "2024-12-04T12:00:00.00Z",
"end": "2024-12-04T17:00:00.00Z"
},
"dropoff_house_number": 2 //custom field
}
]
}
```
### Sample Success Data(Pay on Delivery)
```json
//Sample Request Body
{
"orderType": "PROCESSING",
"pickup": {
"address": "928 Lowe Lakes",
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"pickupDate": "2024-03-22",
"locationCode": "JJ2M",
},
"drops": [
{
"address": "419 Graham View",
"podAmount": 1000,
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"locationCode": "XV4C",
}
]
}
```
### Sample Error Data
```json
// Sample Request Body
{
"orderType": "PROCESSING",
"pickup": {
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"pickupDate": "2024-03-22",
"locationCode": "JJ2M",
},
"drops": [
{
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"locationCode": "XV4C",
}
]
}
```
```json
// Sample Response Body - 400 Bad Request
{
"status": false,
"message": "\"address\" is required, \"address\" is required"
}
```
A 400 Bad Request is returned for any missing required field.