Custom Package Types
If you have your own custom packaging with specific dimensions that you use frequently (either in place of or in addition to carrier-defined packages), you might find it helpful to define those custom package types to use more easily in your shipments. You can then simply include the package_code
property in your shipment object, instead of the individual dimension properties.
Define a Package Type
You can define as many package types as you need, each with their own name, package code, and set of dimensions.
Requirements
The following properties are required in the request body when creating a custom package type:
Property | Type | Description |
---|---|---|
package_code | string | Max 50 characters. This is the code you will use in your shipment objects. Each custom package must add the prefix custom_ to the package_code or the request will be rejected with a HTTP 400, Bad Request status. |
name | string | Max 50 characters. Any custom name you choose to help identify the package. |
dimensions | Object | Requires the unit , length , width , and height properties |
Optional Properties
You can also include a package_id
, which is a string (max 25 characters) that uniquely identifies the package, and a description
, a string of up to 500 characters.
Sample Request & Response
POST /v2/packages/
POST /v2/packages HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "package_code": "custom_laptop_box", "name": "laptop_box", "dimensions": { "unit": "inch", "length": 15, "width": 20, "height": 5 }, "description": "Packaging for laptops." }
Response
The response will simply include all of the packages defined properties.
{ "package_id": "se-100896", "package_code": "custom_laptop_box", "name": "laptop_box", "dimensions": { "unit": "inch", "length": 15.0, "width": 20.0, "height": 5.0 }, "description": "Packaging for laptops." }
List Package Types
List your package types to get a response with an array of all the available custom packaging available in your account.
Sample Request & Response
GET /v2/packages
GET /v2/packages HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__
Response
{ "packages": [ { "package_id": "se-102873", "package_code": "custom_laptop_box", "name": "Custom Laptop Box", "dimensions": { "unit": "inch", "length": 15.00, "width": 20.00, "height": 5.00 }, "description": "" } ] }
Get Custom Package by ID
To obtain details about a specific custom package, like its dimensions and description, you'll use the GET method with the /v2/packages
endpoint and the package_id
.
Sample Request & Response
GET /v2/packages/:package_id
GET /v2/packages/se-100896 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__
Response
{ "package_id": "se-100896", "package_code": "custom_laptop_box", "name": "laptop_box", "dimensions": { "units": "inch", "length": 15.00, "width": 20.00, "height": 5.00 }, "description": "Packaging for laptops." }
Update Custom Package
You can update the individual properties of your custom packages using the PUT method with the /v2/packages
endpoint and the package_id
.
Requirements
- You'll need the
package_id
of the custom package to update. - You'll need to include all the same properties in the request body as when you defined the custom package, with any new values for the properties you'd like to update.
Sample Request & Response
PUT /v2/packages/:package_id
GET /v2/packages/se-100896 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "package_code": "custom_laptop_box", "name": "laptop_box", "dimensions": { "unit": "inch", "length": 15, "width": 22, "height": 5 }, "description": "Packaging for laptops." }
If successful, you'll receive an HTTP Status 204, (No Content) response.
Delete Package Types
Deleting a package will not disassociate it from any shipments. It will merely stop being available for use with future shipments and it will will no longer be included in the list packages response.
You will need the package_id
of the custom package you wish to delete.
Sample Request & Response
DELETE /v2/packages/:package_id
DELETE /v2/packages/se-102873 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__
Response
If successful, you'll receive an HTTP Status 204, No Content response.