New Booking

Request delivery

POST {baseUrl}/deliveries

To create a new delivery booking, provide the following details:

Pick-up Details Include the necessary pick-up information such as address, contact person etc.
Drop-off Details Include drop-off information such as address, contact person etc.
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.
Order Type Set the orderType to PROCESSING. This ensures that the delivery will be handled by your partners.
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 request.
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

{
      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
        }
      ]
    }

{
    "status": false,
    "message": "Invalid app_id or app_secret",
    "data": {
        "statusCode": 401,
        "message": "Invalid app_id or app_secret",
        "isOperational": true,
    }
}

{
    // Response
}

// 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

//Sample Request Body
{  
   "orderType": "PROCESSING",
   "bookingEmail": "[email protected]",
   "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)


//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

// 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",
      }
    ]
}

// 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.

PreviousBookings NextGenerate POD account number

Last updated 1 month ago