New Booking

Request delivery

POST {baseUrl}/deliveries

Create a new delivery booking. Include pick-up details, drop-off details, a unique customerId.

For bookings to be delivered by the Sendstack Network, select orderType: "FULFILLMENT".

For bookings to be delivered by your partners, select orderType: "PROCESSING". You can optionally assign a drop to a partner during booking. In this case, pass the assignedPartner field with the objectId of the partner.

By default, the payment for the booking is charged to your wallet, there's an optional paymentSource field for when the payment for the delivery shouldn't be deducted from your wallet.

Headers

Name	Type	Description
app_id*	String
app_secret*	String

Request Body

Name	Type	Description
customerId	string	Unique customer ID
pickup*	object	Pickup details
drops*	array	Dropoff locations and details
orderType*	string

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": "FULFILLMENT",
   "customerId": "customerId",
    "pickup": {
      "address": "928 Lowe Lakes",
      "pickupName": "Miss Rudolph Dietrich",
      "pickupNumber": "[phone]",
      "altPickupNumber": "[phone]",
      "pickupDate": "2024-03-22",
      "lat": 6.602928,
      "long": 3.345006
    },
    "drops": [
      {
        "address": "419 Graham View",
        "recipientName": "Robyn Nitzsche DVM",
        "recipientNumber": "[phone]",
        "altRecipientNumber": "[phone]"
        "lat": 6.602928,
        "long": 3.345006
      }
    ]
}

Available Fields

paymentSource, //Optional
customerId, //Optional
orderType, //Optional - "PROCESSING" or "FULFILLMENT"
pickup: {
        long, //Optional
        lat, //Optional
        locationCode, //Optional
        city, //Optional
        country, //Optional
        address, //Required,
        pickupName, //Required,
        pickupEmail, //Required,
        pickupNumber, //Required,
        altPickupNumber, //Optional
        note, //Optional
        pickupDate
      },
drops: [{
        long, //Optional
        lat, //Optional
        locationCode, //Optional
        address, //Required,
        recipientName, //Required,
        recipientNumber, //Required,
        recipientEmail, //Required,
        altRecipientNumber, //Required,
        category: Joi.string(),
        note, //Optional
        country, //Optional
        city, //Optional
        packaging: { , //Optional
            height: Joi.number(), 
            length: Joi.number(),
            width: Joi.number(),
            weight: Joi.number(), 
        },
        categoryId, //Optional 
        assignedPartner //Optional,
}],

Sample Success Data(Pay on Delivery)

//Sample Request Body

{  
   "orderType": "FULFILLMENT"
   "customerId": "customerId",
    "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": "FULFILLMENT"
   "customerId": "customerId",
    "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.