API Documentation
Authentication
Authentication and identification to the Shipbuy API Token is done by providing an API Token on every request as your Bearer Token. Shipbuy requires that all communication with the API is secured using TLS v1.2. Requests made over HTTP or without a proper API Token will fail.
You can manage your API Token from your account integration settings.
Errors
In the event of a client or server error, the response will contain the standard 4xx or 5xx respectively, accompanied by a well-formed JSON body describing the issue, e.g., a required field was omitted, a purchase failed, etc.
Each client library will encapsulate these errors and raise an exception, in addition to other exceptional cases, such as network failures. It is recommended to handle exceptions gracefully and to report any issues to support@shipbuy.com.
Error Object
| attribute | type | specification |
|---|---|---|
| code | string | Machine readable description of the problem |
| message | string | Human readable description of the problem |
Shipment API
Shipment API for list rates, buy label, void label and tracking.
Rates
Get available shipping rates.
POST https://shipbuy.com/api/shipping/rates
Example of request and response
curl -X POST https://shipbuy.com/api/shipping/rates \
-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_first_class_mail",
"confirmation_type": null,
"insurance_provider_type": null,
"dimension_unit": "in",
"weight_unit": "oz",
"rate_id": null,
"from": {
"company": null,
"name": "Louis Wu",
"phone": null,
"street1": "19335 balan rd",
"street2": null,
"city": "Rowland Heights",
"state": "CA",
"zip": "91748",
"country": "US",
"residential": true
},
"to": {
"company": null,
"name": "Amy Xu",
"phone": "6268282990",
"street1": "764 windwood dr",
"street2": null,
"city": "Walnut",
"state": "CA",
"zip": "91789",
"country": "US",
"residential": true
},
"packages": [
{
"package_type": null,
"length": 10,
"width": 8,
"height": 6,
"weight": 2.4,
"insurance_amount": null
}
],
"options": null,
"customs": null
}'
{
"rates": [
{
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_parcel_select",
"delivery_days": 3,
"delivery_date": "",
"currency": "usd",
"list_rate": 7.59,
"rate": 7.59,
"insurance": 0,
"surcharges": null,
"rate_id": null
},
{
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_priority_mail",
"delivery_days": 1,
"delivery_date": "",
"currency": "usd",
"list_rate": 8.49,
"rate": 8.49,
"insurance": 0,
"surcharges": null,
"rate_id": null
},
{
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_express_mail",
"delivery_days": -1,
"delivery_date": "",
"currency": "usd",
"list_rate": 24.55,
"rate": 24.55,
"insurance": 0,
"surcharges": null,
"rate_id": null
}
],
"alerts": []
}
Buy
Buy a shipment.
POST https://shipbuy.com/api/shipping/buy
Example of request and response
curl -X POST https://shipbuy.com/api/shipping/buy \
-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_first_class_mail",
"confirmation_type": null,
"insurance_provider_type": null,
"dimension_unit": "in",
"weight_unit": "oz",
"rate_id": null,
"from": {
"company": null,
"name": "Louis Wu",
"phone": null,
"street1": "19335 balan rd",
"street2": null,
"city": "Rowland Heights",
"state": "CA",
"zip": "91748",
"country": "US",
"residential": true
},
"to": {
"company": null,
"name": "Amy Xu",
"phone": "6268282990",
"street1": "764 windwood dr",
"street2": null,
"city": "Walnut",
"state": "CA",
"zip": "91789",
"country": "US",
"residential": true
},
"packages": [
{
"package_type": null,
"length": 10,
"width": 8,
"height": 6,
"weight": 2.4,
"insurance_amount": null
}
],
"options": null,
"customs": null
}'
{
"id": 41071243,
"shipping_account_name": "my usps",
"carrier_type": "usps",
"service_type": "usps_first_class_mail",
"insurance_provider_type": "",
"insurances": [],
"shipping_cost": 3.62,
"shipment_id": "",
"status": "created",
"refund_status": "",
"currency": "usd",
"dimension_unit": "in",
"weight_unit": "oz",
"delivery_days": 2,
"delivery_date": null,
"ship_date": null,
"created_at": null,
"from": {
"name": "Louis Wu",
"company": "",
"phone": "",
"email": "",
"street1": "19335 balan rd",
"street2": "",
"city": "Rowland Heights",
"state": "CA",
"zip": "91748",
"country": "US",
"residential": false
},
"to": {
"name": "Amy Chu",
"company": "",
"phone": "6268282990",
"email": "",
"street1": "764 windwood dr",
"street2": "",
"city": "Walnut",
"state": "CA",
"zip": "91789",
"country": "US",
"residential": false
},
"packages": [
{
"package_type": "",
"length": 10,
"width": 8,
"height": 6,
"weight": 2.4,
"insurance_amount": 0,
"package_id": "shp_e162a93e4c8f4b80d1e90",
"tracking_number": "9400100106089169857853",
"label_url": "https://shipbuy.s3....png"
}
],
"forms": [],
"surcharges": []
}
Refund
Refund a shipment.
POST https://shipbuy.com/api/shipping/refund
Example of request and response
curl -X POST https://shipbuy.com/api/shipping/refund \
-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"id": 41071243
}'
{
"id": 41071243,
"refund_status": "submitted"
}