Skip to main content
POST
/
parcels
cURL
curl https://api.goshippo.com/parcels/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -d length=5 \
  -d width=5 \
  -d height=5 \
  -d distance_unit="cm" \
  -d weight=2 \
  -d mass_unit="lb" \
  -d template="" \
  -d metadata="Customer ID 123456"
{
  "mass_unit": "lb",
  "weight": "1",
  "distance_unit": "in",
  "height": "1",
  "length": "1",
  "width": "1",
  "extra": {
    "COD": {
      "amount": "5.5",
      "currency": "USD",
      "payment_method": "CASH"
    },
    "insurance": {
      "amount": "5.5",
      "content": "Laptop",
      "currency": "USD",
      "provider": "UPS"
    },
    "reference_1": "<string>",
    "reference_2": "<string>"
  },
  "metadata": "Customer ID 123456",
  "object_created": "2014-07-09T02:19:13.174Z",
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_owner": "shippotle@shippo.com",
  "object_state": "VALID",
  "object_updated": "2014-07-09T02:19:13.174Z",
  "template": "FedEx_Box_10kg",
  "test": true
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Parcel details.

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
weight
string
required

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
distance_unit
enum<string>
required

The measure unit used for length, width and height.

Available options:
cm,
in,
ft,
m,
mm,
yd
Example:

"in"

​
height
string
required

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
length
string
required

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
width
string
required

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
extra
Parcel Extra · object

An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.

​
metadata
string
Example:

"Customer ID 123456"

Response

Parcel

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
weight
string
required

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
distance_unit
enum<string>
required

The measure unit used for length, width and height.

Available options:
cm,
in,
ft,
m,
mm,
yd
Example:

"in"

​
height
string
required

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
length
string
required

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
width
string
required

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
extra
Parcel Extra · object

An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.

​
metadata
string
Example:

"Customer ID 123456"

​
object_created
string<date-time>

Date and time of Parcel creation.

Example:

"2014-07-09T02:19:13.174Z"

​
object_id
string

Unique identifier of the given Parcel object. This ID is required to create a Shipment object.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

​
object_owner
string

Username of the user who created the Parcel object.

Example:

"shippotle@shippo.com"

​
object_state
enum<string>

A Parcel will only be valid when all required values have been sent and validated successfully.

Available options:
VALID
Example:

"VALID"

​
object_updated
string<date-time>

Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given.

Example:

"2014-07-09T02:19:13.174Z"

​
template

If template is passed, length, width, height, and distance_unit are not required

Available options:
FedEx_Box_10kg,
FedEx_Box_25kg,
FedEx_Box_Extra_Large_1,
FedEx_Box_Extra_Large_2,
FedEx_Box_Large_1,
FedEx_Box_Large_2,
FedEx_Box_Medium_1,
FedEx_Box_Medium_2,
FedEx_Box_Small_1,
FedEx_Box_Small_2,
FedEx_Envelope,
FedEx_Padded_Pak,
FedEx_Pak_1,
FedEx_Pak_2,
FedEx_Tube,
FedEx_XL_Pak
​
test
boolean

Indicates whether the object has been created in test mode.