Package sizes
Contents 26 pages
A Shopify store's package sizes are the boxes each of its products ships in. They are the same sizes as the Package dimensions page in the ShipEasy app in Shopify admin: an item sized here is sized there, and the store's orders are quoted with them. Sizes are in inches and pounds.
An item is a whole product (every option of it) or one variant. A variant's own
sizes win over its product's for that option. Its id is product_<number> or
variant_<number>, with Shopify's own number.
Package sizes belong to a Shopify store. A web app organization's key gets
shopify_stores_only: an organization keeps a catalog of
models instead.
Reading needs catalog:read; sizing, replacing, deleting, restoring and importing
need catalog:write.
List or search#
/api/v1/package_sizesScope catalog:readcurl "https://app.shipeasyco.com/api/v1/package_sizes?q=oak%20table" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "list",
"data": [
{
"object": "package_size",
"id": "product_8812345678",
"applies_to": "product",
"product_id": "8812345678",
"variant_id": null,
"title": "Oak dining table",
"sku": "DT-210",
"packages": [
{
"package_index": 0,
"length_in": 72,
"width_in": 40,
"height_in": 8,
"weight_lbs": 96
}
],
"updated_at": "2026-11-02T15:04:11.000Z"
}
],
"has_more": false,
"next_cursor": null
}Without q, every sized product and variant comes back in id order, in
pages. With q, ShipEasy asks Shopify for products whose
title matches and returns each one, with its sizes or with packages: [] when it has
none yet, plus each of its variants that has its own. title and sku are what
Shopify holds; they are null when Shopify did not answer.
Read one#
/api/v1/package_sizes/{packageSizeId}Scope catalog:readcurl https://app.shipeasyco.com/api/v1/package_sizes/product_8812345678 \
-H "Authorization: Bearer $SHIPEASY_API_KEY"Size an item#
/api/v1/package_sizesScope catalog:writecurl -X POST https://app.shipeasyco.com/api/v1/package_sizes \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_id": "8812345678",
"packages": [
{ "length_in": 72, "width_in": 40, "height_in": 8, "weight_lbs": 96 },
{ "length_in": 32, "width_in": 12, "height_in": 12, "weight_lbs": 41 }
]
}'Send product_id or variant_id, Shopify's number or its gid://shopify/… id.
Answers 201 with the item. An item that already has sizes is refused with
validation_failed, naming its id: replace them instead.
Replace, delete or restore#
/api/v1/package_sizes/{packageSizeId}Scope catalog:writePATCH takes packages, every box the item ships in: the boxes you send replace
the old ones.
/api/v1/package_sizes/{packageSizeId}Scope catalog:write{ "object": "deleted", "id": "product_8812345678", "deleted": true }/api/v1/package_sizes/{packageSizeId}/restoreScope catalog:writeA delete removes every box of the item. While the item has no sizes, restore
brings back the boxes that delete removed.
Import many items#
/api/v1/package_sizes/importsScope catalog:writeSend up to 500 items in one call, each with product_id or variant_id and its
packages. Each item ends up with exactly the boxes sent; items you leave out are
untouched. Run it with dry_run: true first: nothing changes, and the answer says
what would.
{
"object": "package_size_import",
"dry_run": true,
"added": 1,
"updated": 1,
"items": [
{ "index": 0, "id": "product_8812345678", "result": "update", "problem": null },
{ "index": 1, "id": "variant_4455667788", "result": "add", "problem": null }
]
}Each item is add (it had no sizes), update (its sizes are replaced) or
problem. A real run with any problem item is refused whole with
validation_failed, so nothing half-lands.