Product catalogue API

The product catalogue API stores the size and weight of the products you ship, so Shippit can work out which cartons an order needs without you measuring the same product on every order.

An order measures its products inline through product_attributes. A catalogue measures them once. When both are present the order wins, field by field, so a payload carrying only weight keeps the catalogue's dimensions.

You address items by SKU rather than by an id. A SKU is the identifier you already hold and already treat as unique, and Shippit matches it case-insensitively: create ABC-1 and you can fetch abc-1.

Endpoints

POST/merchants/product_catalogue/itemsadd an item
GET/merchants/product_catalogue/items/{sku}fetch one item by SKU
PATCH/merchants/product_catalogue/items/{sku}change one item
DELETE/merchants/product_catalogue/items/{sku}remove one item

Permissions

Each endpoint checks a permission on the API secret, and each defaults to off. Read access never implies write access: handing an integrator the ability to read your catalogue doesn't let them delete it.

Endpoint	Permission
`GET /merchants/product_catalogue/items/{sku}`	Get Product Catalogue
`POST /merchants/product_catalogue/items`	Create Product Catalogue Item
`PATCH /merchants/product_catalogue/items/{sku}`	Update Product Catalogue Item
`DELETE /merchants/product_catalogue/items/{sku}`	Delete Product Catalogue Item

Units

Measurements are centimetres and grams on this endpoint. That's not the same convention as parcel_attributes and product_attributes, which take metres and kilograms. A 12 cm mug weighing 400 g is length_cm: 12, weight_g: 400 here and length: 0.12, weight: 0.4 on an order.

Shippit stores dimensions to the nearest millimetre, so a length_cm of 12.34 reads back as 12.3. weight_g must be a whole number of grams. Shippit rejects 400.5 with 422 rather than rounding it.

The product catalogue item object

skustringRequired: Stock Keeping Unit code, up to 255 characters. Unique within your catalogue, and how you address every item. May contain dots and dashes.
titlestringRequired: Name of the product, up to 255 characters.
pricestringOptional: Unit price, up to 1,000,000. Returned as a string so it doesn't round-trip through a float.
product_line_idstringOptional: Your identifier for the product line this belongs to.
locationstringOptional: Where your warehouse picks the product from.
origin_country_codestringOptional: Two-letter country code (ISO 3166-1 Alpha-2) for the product's origin country, used in customs declarations.
tariff_codestringOptional: Tariff or HS code for international declarations.
dangerous_goods_codestringOptional: The International Air Transport Association (IATA) or Australian Dangerous Goods Code (ADG) hazard class. Also decides which products may share a carton, because Shippit never packs two different classes together.
dangerous_goods_un_codestringOptional: Four-digit UN number, without the UN prefix: 1950, not UN1950.
dangerous_goods_packing_groupstringOptional: Packing group for the dangerous good.
weight_gnumberOptional: Dead weight of one unit, in grams. Leave it out when you don't know it: unless the order sends a weight, Shippit packs each unit as 1 kg.
length_cmnumberRequired: Length of one unit, in centimetres.
width_cmnumberRequired: Width of one unit, in centimetres.
depth_cmnumberRequired: Depth of one unit, in centimetres.
separate_pack_requiredbooleanOptional: Ship this product in its own carton, never alongside anything else.
fragilebooleanOptional: Whether the product is fragile.
stackablebooleanOptional: Whether other items can sit on top of it.
compressiblebooleanOptional: Whether the product compresses under load.
orientation_lockstringOptional: this_side_up or flat_only. Shippit rejects any other value. Leave it out when the product can go any way up.
non_standard_manufacturer_pidstringOptional: The manufacturer's own part number for the product, up to 70 characters. EU customs calls this the Non-Standardised Manufacturer Product Identifier (PID).
standard_manufacturer_pidstringOptional: The product's barcode number, such as a Global Trade Item Number (GTIN), European Article Number (EAN), Universal Product Code (UPC), or International Standard Book Number (ISBN), up to 70 characters. EU customs calls this the Standardised Manufacturer PID.
eudr_dds_referencestringOptional: The EU Deforestation Regulation (EUDR) Due Diligence Statement reference number, up to 70 characters. Some goods shipped into the EU need one, such as coffee, cocoa, timber, and leather.
eudr_document_codestringOptional: The EUDR document code from the EU Integrated Tariff (TARIC), up to 70 characters, for example C716 or Y133. This isn't the HS code. Send that in tariff_code.

The four EU customs identifiers are optional. Shippit trims them and treats a blank as not provided, and rejects a value over 70 characters with 422.

ResponseJSON

{
    "product_catalogue_item": {
        "sku": "MUG-12OZ-WHT",
        "title": "Ceramic mug (12oz)",
        "price": "24.0",
        "product_line_id": "PL1",
        "location": "A1-04",
        "origin_country_code": "AU",
        "tariff_code": "691200",
        "dangerous_goods_code": null,
        "dangerous_goods_un_code": null,
        "dangerous_goods_packing_group": null,
        "weight_g": 400,
        "length_cm": 12.0,
        "width_cm": 12.0,
        "depth_cm": 10.0,
        "separate_pack_required": false,
        "fragile": true,
        "stackable": true,
        "compressible": false,
        "orientation_lock": "this_side_up",
        "non_standard_manufacturer_pid": "MUG-12-W",
        "standard_manufacturer_pid": "9312345678907",
        "eudr_dds_reference": null,
        "eudr_document_code": null
    }
}

Retrieve a catalogue item

GET/merchants/product_catalogue/items/{sku}

Fetches one item. Shippit matches the SKU case-insensitively, and it may contain dots, so /merchants/product_catalogue/items/ABC-1.5 resolves as the SKU ABC-1.5 rather than as ABC-1 in a .5 format.

Shippit only looks in your own catalogue, so another merchant's SKU returns 404 rather than resolving.

Response codes

Status	Meaning	Description
200	OK	The item.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
404	Not Found	No item with that SKU in your catalogue.

Create a catalogue item

POST/merchants/product_catalogue/items

Send sku, title, and the three dimensions. weight_g is optional. Measurements must be greater than zero. Dimensions can be up to 600 cm, and weight up to 1,000 kg.

Returns the created item with 201 Created.

Response codes

Status	Meaning	Description
201	Created	The created item.
400	Bad Request	The body has no `product_catalogue_item` object, or it's empty.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
422	Unprocessable Entity	A field failed validation, or the SKU already exists in your catalogue. The message names the field, for example `SKU is already used by another product in this catalogue`.

RequestJSON

{
    "product_catalogue_item": {
        "sku": "MUG-12OZ-WHT",
        "title": "Ceramic mug (12oz)",
        "weight_g": 400,
        "length_cm": 12,
        "width_cm": 12,
        "depth_cm": 10,
        "fragile": true
    }
}

Update a catalogue item

PATCH/merchants/product_catalogue/items/{sku}

Updates only the fields you send. Anything you leave out keeps its stored value.

Returns the updated item.

Response codes

Status	Meaning	Description
200	OK	The updated item.
400	Bad Request	The body has no `product_catalogue_item` object, or it's empty.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
404	Not Found	No item with that SKU in your catalogue.
422	Unprocessable Entity	A field failed validation, or you changed `sku` to one that already exists in your catalogue. The message names the field.

ResponseJSON

{
    "product_catalogue_item": {
        "weight_g": 450
    }
}

Delete a catalogue item

DELETE/merchants/product_catalogue/items/{sku}

Removes the item. Returns 204 No Content with an empty body.

Deleting doesn't change orders already placed, because they carry their own measurements. Later orders for that SKU fall back to whatever the order itself measures, or to your account's unknown-product setting.

Response codes

Status	Meaning	Description
204	No Content	Shippit deleted the item.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
404	Not Found	No item with that SKU in your catalogue.