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

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: '[phone]',
        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: '[phone]',
          //...truncated for brevity
        }
      ]
    }

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,
    }
}

422: Unprocessable Entity Low wallet balance

{
    // 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": "[e-mail]",
   "bookingName": "test",
    "pickup": {
      "address": "928 Lowe Lakes",
      "pickupName": "Miss Rudolph Dietrich",
      "pickupNumber": "[phone]",
      "altPickupNumber": "[phone]",
      "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": "[phone]",
        "altRecipientNumber": "[phone]",
        "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": "[phone]",
      "pickupDate": "2024-03-22",
      "locationCode": "JJ2M",
    },
    "drops": [
      {
        "address": "419 Graham View",
        "podAmount": 1000,
        "recipientName": "Robyn Nitzsche DVM",
        "recipientNumber": "[phone]",
        "locationCode": "XV4C",
      }
    ]
}

Sample Error Data

// Sample Request Body
{  
   "orderType": "PROCESSING",
    "pickup": {
      "pickupName": "Miss Rudolph Dietrich",
      "pickupNumber": "[phone]",
      "pickupDate": "2024-03-22",
      "locationCode": "JJ2M",
    },
    "drops": [
      {
        "recipientName": "Robyn Nitzsche DVM",
        "recipientNumber": "[phone]",
        "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.