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"
}