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.
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.
attribute | type | specification |
---|---|---|
code | string | Machine readable description of the problem |
message | string | Human readable description of the problem |
Shipment API for list rates, buy label, void label and tracking.
Get available shipping rates.
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 a shipment.
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 a shipment.
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"
}