Skip to content

Catalog

Contents 26 pages

Your catalog is the list of products you ship and the boxes each one ships in. It is the same catalog as the Catalog page in the web app: a model added here shows up there, and on the quote page's search. Sizes are in inches and pounds.

Quoting one unit of a model ships one of each of its boxes. To quote by model, send a handling unit with its model_code and quantity instead of the four sizes (see Quote a model).

The catalog belongs to a web app organization. A Shopify store's key gets not_available_for_shopify: a store's package sizes live with its Shopify products.

Reading needs catalog:read; adding, changing, deleting and importing need catalog:write.

GET/api/v1/catalogScope catalog:read
Request
curl "https://app.shipeasyco.com/api/v1/catalog?q=dining" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"object": "list",
	"data": [
		{
			"object": "catalog_model",
			"id": "cm4q8x1b2…",
			"model_code": "DT-210",
			"model_name": "OAK DINING TABLE",
			"brand": "northwood",
			"category": "TABLES",
			"source": "manual",
			"boxes": [
				{
					"box_number": 1,
					"length_in": 72,
					"width_in": 40,
					"height_in": 8,
					"weight_lbs": 96,
					"packing_qty": 1
				},
				{
					"box_number": 2,
					"length_in": 32,
					"width_in": 12,
					"height_in": 12,
					"weight_lbs": 41,
					"packing_qty": 1
				}
			],
			"total_weight_lbs": 137,
			"total_volume_ft3": 16.0,
			"created_at": "2026-11-02T15:04:11.000Z",
			"updated_at": "2026-11-02T15:04:11.000Z"
		}
	],
	"has_more": false,
	"next_cursor": null
}

Without q, every model comes back, newest first, in pages. With q, it is the quote page's search: the best matches on name, code, brand or category, at most 8, in one page.

source says how a model got here: upload (a file or an import), manual (typed in, or edited since) or store (imported from a connected store and untouched).

Read one#

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

Add a model#

POST/api/v1/catalogScope catalog:write
Shell
curl -X POST https://app.shipeasyco.com/api/v1/catalog \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_code": "DT-210",
    "model_name": "Oak dining table",
    "brand": "Northwood",
    "category": "Tables",
    "boxes": [
      { "length_in": 72, "width_in": 40, "height_in": 8, "weight_lbs": 96 },
      { "length_in": 32, "width_in": 12, "height_in": 12, "weight_lbs": 41 }
    ]
  }'

Answers 201 with the model. Codes, names and categories are stored in capitals, brands in lower case. A code already in the catalog is refused with validation_failed, naming the model that holds it: change that one instead.

Replace or delete a model#

PATCH/api/v1/catalog/{modelId}Scope catalog:write

PATCH takes the whole model, every box included, as POST does: the boxes you send replace the old ones. A model imported from a connected store becomes a manual one.

DELETE/api/v1/catalog/{modelId}Scope catalog:write
Request
curl -X DELETE https://app.shipeasyco.com/api/v1/catalog/cm4q8x1b2… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{ "object": "deleted", "id": "cm4q8x1b2…", "deleted": true }

A delete is for good. Quotes and shipments already made keep their own copy of the sizes.

Import many models#

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

Send up to 500 models in one call. Run it with dry_run: true first: nothing changes, and the answer says what would.

Request
curl -X POST https://app.shipeasyco.com/api/v1/catalog/imports \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "items": [
      { "model_code": "DT-210", "model_name": "Oak dining table",
        "boxes": [{ "length_in": 72, "width_in": 40, "height_in": 8, "weight_lbs": 96 }] },
      { "model_code": "CH-4", "model_name": "Side chair",
        "boxes": [{ "length_in": 22, "width_in": 20, "height_in": 36, "weight_lbs": 0 }] }
    ]
  }'
Response
{
	"object": "catalog_import",
	"dry_run": true,
	"mode": "merge",
	"added": 0,
	"updated": 1,
	"removed": 0,
	"items": [
		{ "index": 0, "model_code": "DT-210", "result": "update", "problem": null },
		{
			"index": 1,
			"model_code": "CH-4",
			"result": "problem",
			"problem": "Box 1: weight_lbs must be a positive number."
		}
	]
}

Each item is add (new code), update (replaces the model with the same code) or problem. A real run with any problem item is refused whole with validation_failed, one issue per item, so nothing half-lands: fix those items or leave them out, and send again with dry_run: false.

mode is merge by default: the items are added, and a model with the same code is replaced, boxes and all; every other model stays. mode: "replace" empties the catalog first, so the catalog becomes exactly items; removed says how many models that drops. A real replace also needs confirm_replace: true, sent only once the person whose catalog it is has agreed.

For a catalog bigger than one call, send several merges. For a messy spreadsheet, a PDF or a photo, the web app's Catalog page reads the file with AI and shows what it found before anything is saved.

Quote a model#

A handling unit in POST /quotes or POST /quotes/bulk may name a model instead of its sizes:

JSON
{ "model_code": "DT-210", "quantity": 3 }

quantity is then the number of units of the model, a whole number. ShipEasy sends each of the model's boxes, each quantity ÷ packing_qty times rounded up: three chairs packed two to a box ship as two boxes. The description is the model's name and code unless you send one. A code not in the catalog is refused at that unit (handling_units[1].model_code), and the boxes count against the shipment's caps like typed units. Shopify stores send sizes; their package sizes are read when an order is quoted.