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.
List or search#
/api/v1/catalogScope catalog:readcurl "https://app.shipeasyco.com/api/v1/catalog?q=dining" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"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#
/api/v1/catalog/{modelId}Scope catalog:readcurl https://app.shipeasyco.com/api/v1/catalog/cm4q8x1b2… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"Add a model#
/api/v1/catalogScope catalog:writecurl -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#
/api/v1/catalog/{modelId}Scope catalog:writePATCH 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.
/api/v1/catalog/{modelId}Scope catalog:writecurl -X DELETE https://app.shipeasyco.com/api/v1/catalog/cm4q8x1b2… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{ "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#
/api/v1/catalog/importsScope catalog:writeSend up to 500 models in one call. Run it with dry_run: true first: nothing
changes, and the answer says what would.
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 }] }
]
}'{
"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:
{ "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.