# Create New Shipment ## Sample Payload to request shipment ```json { "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" : "+234 800 666 0419", "lng" : 3.37, "lat" : 6.56, "name" : null }, "destination": { "first_name": "Joe", "last_name": "Goldberg", "post_code": "94612", "phone": "+1 267 000 0", "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`](https://api.sendbox.co/shipping/shipments) This creates a new shipment {% tabs %} {% tab title="Request" %} ## Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | String | Authorization-key | | Content-type | String | application/json | ## Body Parameters
NameTypeDescription
NameTypeDescription
originObjectsenders details
destinationObjectrecipient details
weightFloatweight of package
itemsArray

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_optionStringset to either pickup or dropoff
pickup_dateDatedate in ISO format
total_valueFloatvalue of shipment
package_typeStringpackage type
channel_code Stringchannel the request is being made from; in this case set it to api
service_codeStringcan be set to either international, nation-wide, and local.
regionStringregion the shipment is being shipped from.
custom_optionsStringcustom options
callback_urlStringa webhook url to get the tracking update.
hts_codeStringpass in the item code to match it's description.
{% endtab %} {% tab title="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. ```json { "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": "sales@quinn.com", "phone": "+19400080111" }, "pk": "66ba41348f1bd40039f8f38a", "package_connector_other_charge": 0.0, "destination_city": "paris", "date_booked": "2024-08-12T17:07:00.072000", "origin_phone": "+2348006660419", "destination_name": "Forty Quinn", "current_awb": null, "courier": { "name": "" }, "origin_country_code": "NG", "destination_phone": "+12672306531", "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 } ``` {% endtab %} {% endtabs %} ### 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 {% embed url="" %} {% tabs %} {% tab title="Request" %} ```json { "amount": 10000 } ``` {% endtab %} {% tab title="Response" %} ```json { "status": "successful" } ``` {% endtab %} {% endtabs %} ### Check your staging account balance You can simply do this by doing a get to the staging payment profile ### Stimulate webhooks events You can stimulate webhook events for tracking status on staging by sending tracking code to move\_tracking endpoint ``` { code: } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sendbox.co/shipping/create-new-shipment.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.