Create New Shipment

Creating a new shipment requires you making a post request to the shipment endpoint ensure to pass the required header parameters and body parameters to get the appropriate response

Sample Payload to request shipment

{
    "origin_name": "Mrs. Hippo",
    "origin_phone": "+2348170441446",
    "origin_street": "Clayton St.",
    "origin_city": "Ikorodu",
    "origin_country": "NIGERIA",
    "origin_country_code": "NG",  -------->(optional)
    "origin_state": "Lagos",
    "origin_state_code": "LOS", ------------>(optional)
    "origin_post_code":"10100",
    "destination_name": "Brian",
    "destination_phone": "+2348170441446",
    "destination_street": "Drydock Ave Suite 610",
    "destination_city": "Ikeja",
    "destination_country": "NIGERIA",
    "destination_country_code": "NG", ---------->(optional)
    "destination_state": "Lagos",
    "destination_state_code": "LOS", ---------->(optional)
    "$destination_post_code":"1001",
    "weight": "0.5",
    "items": [
        {
            "name": "Test Brian Iyoha",
            "quantity": "1",
            "weight": "1",
            "amount": "100",
            "value": "120000"
    
    }
    ],
    "selected_courier_id": "rate_key_cb2d48e5eb1fddbe8815b154812f675f",
    "channel_code": "api"
    "insurance_option":"standard"
}

Staging URL: https://sandbox.staging.sendbox.co/shipping/shipments

Create New Shipment

https://live.sendbox.co/shipping/shipments

This creates a new shipment

Headers

Name

Type

Description

Authorization

String

Authorization-key

Content-type

String

application/json

Body Parameters

Name

Type

Description

origin_country

String

senders country

origin_state

String

senders state

origin_street

String

senders street

origin_city

String

senders city

origin_email

String

senders email address

origin_phone

String

senders phone number

destination_country

String

recipient country

destination_state

String

recipient state

destination_city

String

recipient city

destination_street

String

recipient street

destination_email

String

recipient email address

destination_phone

String

recipient phone number

weight

Float

weight of package

selected_courier_id

Float

selected courier id.

items

Array

array of objects including name, weight, item_type_code, package_size_code and quantity

incoming_option_code

String

set to either pickup or dropoff

payment_option_code

String

set this to "prepaid"

channel_code

String

set this to "api"

pickup_date

Date

date in ISO format

deliver_priority_code

String

set this to "next_day"

callback_url

String

a webhook url to get the tracking update.

insurance_option

String

this can be either standard or extended.

201: Created

Create shipment response returns details of the new shipment created. The status code is dependent on available balance in your Sendbox wallet if there is enough money at the time of creating shipment, the wallet is charged and status code is pending but without sufficient balance or empty wallet, status code comes back as drafted.

{
  "code": "07204740",
  "status_code": "drafted",
  "height": 0,
  "time_schedule": {
    "code": "anytime",
    "name": "Anytime"
  },
  "is_spillable": false,
  "destination_address": "10 herbert macualy way zone 5 Lagos Nigeria",
  "incoming_option": {
    "code": "pickup",
    "name": "Pickup"
  },
  "payment_options": null,
  "delivery_priority_code": "next_day",
  "width": 0,
  "origin_name": "Mobolaji Fashahun",
  "short_origin_address": "Ketu Lagos Nigeria",
  "delivery_type_code": "last_mile",
  "destination_city": "zone 5",
  "recurrent_cards": [],
  "origin_state": {
    "code": "LOS",
    "name": "Lagos"
  },
  "pk": "830558",
  "transaction_id": null,
  "merchant": {
    "username": null,
    "email": "akins.rotola@gmail.com",
    "id": 11,
    "phone": "08126466955",
    "name": "Rotola Akinsowon"
  },
  "delivery_priority": {
    "code": "next_day",
    "name": "Next Day"
  },
  "payment_option": {
    "code": "prepaid",
    "name": "Prepaid"
  },
  "courier": {
    "subdomain": null,
    "id": 0,
    "name": null
  },
  "total_value": 0,
  "origin_address": "34 ajibola crescent alapere Ketu Lagos Nigeria",
  "min_quoted_fee": 1000,
  "destination_country": {
    "code": "NG",
    "name": "Nigeria"
  },
  "max_quoted_fee": 1150,
  "destination_email": null,
  "destination_name": "Kenneth Igbokwe",
  "notes": null,
  "use_selected_rate": null,
  "destination_street": "10 herbert macualy way",
  "reference_code": null,
  "selected_rate_id": null,
  "pod": "Prepaid",
  "destination_state": {
    "code": "LOS",
    "name": "Lagos"
  },
  "shipment_id": null,
  "last_updated": "2018-02-21T10:13:39.438992",
  "weight": 1.5,
  "amount_to_receive": 28000.24,
  "destination_state_code": "LOS",
  "sensitivity": "",
  "origin_state_code": "LOS",
  "origin_country_code": "NG",
  "id": 830558,
  "has_waybill": null,
  "short_destination_address": "zone 5 Lagos Nigeria",
  "is_fragile": false,
  "payment_option_code": "prepaid",
  "origin_email": null,
  "pickup_date": "2017-04-18T11:42:42.694000",
  "destination_country_code": "NG",
  "status": {
    "code": "drafted",
    "name": "Booked on Hold"
  },
  "origin_country": {
    "code": "NG",
    "name": "Nigeria"
  },
  "destination_phone": "08111106655",
  "time_schedule_code": "anytime",
  "incoming_option_code": "pickup",
  "origin_city": "Ketu",
  "courier_id": null,
  "merchant_id": 11,
  "package_type_code": "food",
  "is_confidential": false,
  "origin_street": "34 ajibola crescent alapere",
  "items": [
    {
      "description": null,
      "weight": 1.5,
      "amount_to_receive": 0,
      "package_size_code": "medium",
      "item_type_code": "letter_or_document",
      "id": 819886,
      "name": "another thing",
      "accept_value_on_delivery": false,
      "value": 0,
      "item_type": {
        "code": "letter_or_document",
        "name": "Letters or Documents"
      },
      "reference_code": null,
      "quantity": 1
    },
    {
      "description": null,
      "weight": 0,
      "amount_to_receive": 0,
      "package_size_code": "medium",
      "item_type_code": "letter_or_document",
      "id": 819885,
      "name": "something",
      "accept_value_on_delivery": false,
      "value": 0,
      "item_type": {
        "code": "letter_or_document",
        "name": "Letters or Documents"
      },
      "reference_code": null,
      "quantity": 1
    }
  ],
  "package_type": {
    "code": "food",
    "name": "Ready to Eat Meals"
  },
  "accept_value_on_delivery": false,
  "origin_phone": "08126466955",
  "length": 0,
  "date_created": "2018-02-21T10:13:39.404007",
  "delivery_type": {
    "code": "last_mile",
    "name": "Door to Door Delivery"
  },
  "quantity": 2
}

Payload Explained

While some of the payloads are self explained, lets go over some of them that seem a bit confusing.

Selected_courier_id

This should be gotten based on the value of courier_id selected when shipping quotes endpoint is called.

channel_code

This tells us where the request came from this case it's form the api.

Items

This is an array of object it includes name(s) of what you are shipping, weight, item_type_code, package_size_code, value which is the price of the item(s) you are shipping and quantity of your shipment an example of items payload will look like this

"items": [
		{
			"name": "Laptop",
			"item_type_code": "other",
			"package_size_code": "medium",
			"quantity": 2,
			"weight": 3,
			"value":120000
		}
	]

Callback_url

This should be a webhook url which you will pass with your other request shipment payloads. Sendbox will post tracking updates to this url from pending, processing and completed.

Book a shipment without fetching quotes first.

You can create a shipment without fetching quotes by passing "rate_code":"standard" in the create shipment payload.

Fund your staging account

To stimulate a successful request on your staging account you have to fund your staging account by doing a post to add_money endpoint

https://sandbox.staging.sendbox.co/payments/staging/add_money

{
   "amount" : 100000
}

Check your staging account balance

You can simply do this by doing a get to the staging payment profile

https://sandbox.staging.sendbox.co/payments/profile

Stimulate webhooks events

You can stimulate webhook events for tracking status on staging by sending tracking code to move_tracking endpoint

https://sandbox.staging.sendbox.co/dispatch/staging/move_tracking

{
  code: <tracking_code>
}

PreviousRequest Shipping Quotes NextTracking Shipment

Last updated 1 month ago