Skip to content

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.

GET/api/v1/package_sizesScope catalog:read
Request
curl "https://app.shipeasyco.com/api/v1/package_sizes?q=oak%20table" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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#

GET/api/v1/package_sizes/{packageSizeId}Scope catalog:read
Shell
curl https://app.shipeasyco.com/api/v1/package_sizes/product_8812345678 \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

Size an item#

POST/api/v1/package_sizesScope catalog:write
Shell
curl -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#

PATCH/api/v1/package_sizes/{packageSizeId}Scope catalog:write

PATCH takes packages, every box the item ships in: the boxes you send replace the old ones.

DELETE/api/v1/package_sizes/{packageSizeId}Scope catalog:write
JSON
{ "object": "deleted", "id": "product_8812345678", "deleted": true }
POST/api/v1/package_sizes/{packageSizeId}/restoreScope catalog:write

A delete removes every box of the item. While the item has no sizes, restore brings back the boxes that delete removed.

Import many items#

POST/api/v1/package_sizes/importsScope catalog:write

Send 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.

JSON
{
	"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.