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" : {
            "first_name" : "Will",
            "last_name" : "Smith",
            "street" : "10 Olasheun Crescent",
            "street_line_2" : "HQ",
            "state" : "Lagos",
            "email" : null,
            "city" : "Obanikoro",
            "country" : "NG",
            "post_code" : "102216",
            "phone" : "[phone]",
            "lng" : 3.37,
            "lat" : 6.56,
            "name" : null
        },
    "destination": {
        "first_name": "Joe",
        "last_name": "Goldberg",
        "post_code": "94612",
        "phone": "[phone]",
        "lng": -122.27,
        "lat": 37.81,
        "name": null,
        "street": "31 Hall Crescent",
        "street_line_2": "",
        "state": "paris",
        "email": "",
        "city": "paris",
        "country": "FR"
    },
    "weight" : 2,
        "dimension" : {
            "length" : 1,
            "width" : 1,
            "height" : 1
        },
        "incoming_option" : "pickup",
        "region" : "NG",
        "service_type" : "international",
        "package_type" : "general",
        "total_value" : 15000,
        "currency" : "NGN",
        "channel_code" : "api",
        "pickup_date" : "2023-07-20",
        "items" : [
            {
                "item_type" : "snail",
                "hts_code":"9000.10",
                "quantity" : 2,
                "name" : "African Wax Fabrics - Orange Lace Fabric that is Not Woven",
                "value" : 1500
            }
        ],
        "service_code": "standard",
        "customs_option": "recipient",
        "callback_url":"https://your_callback_url/"
        
}

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

Create New Shipment

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

This creates a new shipment

Request

Headers

Name	Type	Description
Authorization	String	Authorization-key
Content-type	String	application/json

Body Parameters

Name	Type	Description
origin	Object	senders details
destination	Object	recipient details
weight	Float	weight of package
items	Array	An array of objects that contain: - name [String] - weight [Float] - item_type_code [String optional] - hts_code [String optional] - description [String] - quantity [Integer] - value [Float]
incoming_option	String	set to either pickup or dropoff
pickup_date	Date	date in ISO format
total_value	Float	value of shipment
package_type	String	package type
channel_code	String	channel the request is being made from; in this case set it to api
service_code	String	can be set to either international, nation-wide, and local.
region	String	region the shipment is being shipped from.
custom_options	String	custom options
callback_url	String	a webhook url to get the tracking update.
hts_code	String	pass in the item code to match it's description.

Response

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.

{
    "pickup_date": "2024-08-14 14:00:54.767000",
    "has_waybill_error": true,
    "selected_courier_id": "65901e2c2291eb2af1f23b4f",
    "origin_city": "obanikoro",
    "pickup_courier": {},
    "code": "0002159289",
    "recurrent_cards": [],
    "origin_name": "Emotu Balogun",
    "delivery_priority": {},
    "origin_state": {
        "name": "lagos",
        "code": "lagos"
    },
    "package_invoice_image": null,
    "destination_state_name": "paris",
    "current_status": {
        "name": "Book On Hold",
        "code": "drafted"
    },
    "user_id": "66952257b84051001f2a2ace",
    "destination_country": {
        "name": "FR",
        "code": "FR"
    },
    "date_created": "2024-08-12T17:07:00.072000",
    "weight": 2.0,
    "paid": 0.0,
    "pod": "prepaid",
    "destination_state_code": "paris",
    "payment_data": {
        "checkout_id": "b32b6dbc7e3cf0a44083d252c5948705",
        "status": "pending",
        "entity_id": null,
        "currency": "NGN",
        "reference_code": "0002159289",
        "payment_source_code": null,
        "amount": 33117.0
    },
    "destination_state": {
        "name": "paris",
        "code": "paris"
    },
    "destination_email": "",
    "origin_country": {
        "name": "NG",
        "code": "NG"
    },
    "origin_state_code": "lagos",
    "destination_country_name": "FR",
    "items": [
        {
            "name": "African Wax Fabrics - Orange Lace Fabric that is Not Woven",
            "weight": 2.0,
            "quantity": 2,
            "piece_id": "0002159289-01",
            "description": "African Wax Fabrics - Orange Lace Fabric that is Not Woven",
            "item_type": {
                "name": "snail",
                "code": "snail"
            },
            "value": 1500.0
        }
    ],
    "region": "NG",
    "status_code": "drafted",
    "fee": 33117.0,
    "status": {
        "name": "Book On Hold",
        "code": "drafted"
    },
    "package_type": {
        "weight": 10.0,
        "name": "General items",
        "description": "Everyday products for various uses."
    },
    "origin_country_name": "NG",
    "possible_actions": [
        {
            "name": "Pay",
            "code": "pay"
        },
        {
            "name": "Cancel",
            "code": "cancel"
        }
    ],
    "tracking_code": "0002159289",
    "amount": 33117.0,
    "package_delivery_attempt": 0,
    "_id": "66ba41348f1bd40039f8f38a",
    "origin_email": null,
    "insurance_option_code": "standard",
    "origin_state_name": "lagos",
    "origin_street": "10 Olasheun Crescent",
    "last_updated": "2024-08-12T17:07:07.214271",
    "incoming_option": {
        "name": null,
        "code": null
    },
    "id": "66ba41348f1bd40039f8f38a",
    "merchant": {
        "name": "Love Quinn",
        "email": "[e-mail]",
        "phone": "[phone]"
    },
    "pk": "66ba41348f1bd40039f8f38a",
    "package_connector_other_charge": 0.0,
    "destination_city": "paris",
    "date_booked": "2024-08-12T17:07:00.072000",
    "origin_phone": "[phone]",
    "destination_name": "Forty Quinn",
    "current_awb": null,
    "courier": {
        "name": ""
    },
    "origin_country_code": "NG",
    "destination_phone": "[phone]",
    "destination_street": "31 Hall Crescent",
    "max_quoted_fee": 33117.0,
    "selected_courier": "65901e2c2291eb2af1f23b4f",
    "min_quoted_fee": 33117.0,
    "waybill_error": "Insufficient item description. Please update to continue",
    "courier_id": "64f020fcf040ba4b3c1697e9",
    "destination_country_code": "FR",
    "quantity": 1.0,
    "total_value": 1500.0
}

Payload Explained

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

channel_code

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

Items

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

"items": [
		{
			"name": "Laptop",
			"item_type_code": "other",
			"hts_code": "9001.10",
			"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.

Fund your staging account

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

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

Request

{
  "amount": 10000
}

Response

{
    "status": "successful"
}

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

{
  code: <tracking_code>
}