Parcels

The Parcels Object

Attribute	Data Type	Description
object_state	"VALID"	A Parcel will only be valid when all required values have been sent and validated successfully.
object_created	datetime	Date and time of Address creation.
object_updated	datetime	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.
object_id	string	Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
object owner	string	Username of the user who created the Parcel object.
length	decimal (10,4)	Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
width	decimal (10,4)	Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
height	decimal (10,4)	Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
distance_unit	"cm", "in", "ft", "mm", "m", "yd"	The unit used for length, width and height.
weight	decimal (10,4)	Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
mass_unit	"g", "oz", "lb", "kg"	The unit used for weight.
template	string	A parcel template is a predefined package used by one or multiple carriers. See the parcel template table for all available values and the corresponding tokens. When a template is given, the parcel dimensions have to be sent, but will not be used for the Rate generation. The dimensions below will instead be used. The parcel weight is not affected by the use of a template.
metadata	string	A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra	object	An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services.

Parcel Extras

The following values are support for the extra field of the parcel object.

Value	Data Type	Description
COD	object	Specify collection on delivery details (UPS, and FedEx only)
COD.amount	string	Amount to be collected
COD.currency	ISO 4217 currency code (string)	Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
COD.payment_method	"SECURED_FUNDS", "CASH", "ANY"	Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
insurance	object	Specify collection on delivery details (UPS, and FedEx only).
insurance.amount	string	Amount to be collected.
insurance.currency	ISO 4217 currency code (string)	Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
insurance.provider	"FEDEX", "UPS"	Specify the carrier insurance to have Insurance provided by the carrier directly.
insurance.content	string	Specify package content for insurance.

POST Create a New Parcel

A POST to the /parcel resource to allow your application to create a new parcel object.

/parcels/

BODY PARAMETERS

Attributes	Required/Optional	Data Type
length	required	decimal (10, 4)
width	required	decimal (10, 4)
height	required	decimal (10, 4)
distance_unit	required	“cm”, “in”, “ft”, “mm”, “m”, “yd”
weight	required	decimal (10, 4)
mass_unit	required	“g”, “oz”, “lb”, “kg”
template	optional	string
extra	optional	object
metadata	optional	string

EXAMPLE REQUEST (Create a Parcel):

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"

EXAMPLE RESPONSE (from Create a Parcel):

{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street1":"215 Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}

GET Retrieve a Parcel

A GET to the /parcel resource to allow your application to retrieve an existing parcel by object ID.

/parcels/{parcel object id}

PATH PARAMETERS

Parameter	Required/Optional	Data Type	Description
Parcel Object ID	required	string	parcel object id

EXAMPLE REQUEST (Retrieve a Parcel)

curl https://api.goshippo.com/parcels/7df2ecf8b4224763ab7c71fae7ec8274/ \
   -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from Retrieve a Parcel):

{
   "object_state":"VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "test": true
}

GET List All Parcels

A GET to the /parcel resource to allow your application to list all parcel objects.

/parcels/

EXAMPLE REQUEST (List All Parcels)

curl https://api.goshippo.com/parcels/ \
   -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from List All Parcels)

{
   "next":null,
   "previous":null,
   "results":[
      {
         "is_complete": true,
         "object_created":"2014-07-16T23:20:31.089Z",
         "object_updated":"2014-07-16T23:20:31.089Z",
         "object_id":"747207de2ba64443b645d08388d0309c",
         "object_owner":"shippotle@goshippo.com",
         "validation_results": {},
         "name":"Shawn Ippotle",
         "street1":"215 Clayton St.",
         "street2":"",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94117",
         "country":"US",
         "phone":"15553419393",
         "email":"shippotle@goshippo.com",
         "is_residential":true,
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}