Products

Use the Products module to maintain a product catalog for your SKUs. The catalog enriches shipments at booking time and powers product-level reporting. Your PIM, ERP, or commerce platform remains the source of truth. Carriyo holds an operational copy, not a master record.

The catalog's main jobs:

• Customs paperwork accuracy. Cross-border shipments need HS codes, country of origin, and material composition per item. Carrying these on the catalog (per SKU) means every shipment that includes that SKU gets the right customs data without re-entering it.
• Default item descriptions. Customer-facing labels and notifications can fall back to a catalog description when the order line doesn't have one.
• Operational rules. Allocation, automation, and service-level rules can match on product attributes (category, dangerous-goods flag, weight, value).
• SKU-level reporting. "Top returned products", "top shipped SKUs", "product performance by region": reports that lean on the catalog.

What's on a product record

Per SKU:

• Identifiers. Three lookup keys: product_id (Carriyo-assigned, unique per tenant), product_ref (your reference, recommended unique within a merchant), and sku (not enforced unique). Plus barcode.
• Classification. Category, sub-category, custom tags.
• Customs metadata. HS code, country of origin, material composition.
• Physical metadata. Weight, dimensions (when standardized at the SKU level rather than per shipment).
• Hazard / restriction flags. Dangerous goods, battery type, age-restricted, etc.
• Custom attributes. Tenant-defined fields.
• Pricing reference. Optional. Typically the order line carries pricing per transaction, but catalog can hold a reference price.

Which identifier resolves the product

Three keys exist, but not every part of the platform accepts all three.

Order line items try product_ref first, then sku, then product_id. Because SKU isn't unique, a SKU that matches several products resolves to the first one found. Send product_ref or product_id when it matters which product you get.

The storefront delivery-options endpoints resolve by product_ref or product_id only. sku is not a lookup key there. A line carrying nothing but a SKU resolves to no product at all, so there is nothing for Carriyo to price or check stock against.

A resolved product writes product_id and inventory_key back onto the line. Stock is then read by inventory_key, never by SKU and never by product reference.

How catalog data enriches a shipment

When you create a shipment with items: [{ sku, quantity, ... }], Carriyo can resolve each SKU against the catalog and fill in the metadata your shipment needs:

• Cross-border: HS code, origin, materials populate from the catalog if not supplied on the line.
• Dangerous goods flags trigger carrier-specific handling.
• Weight defaults apply if parcel-level weights aren't provided.

The order line can still override ("this specific shipment uses this specific weight"), but catalog defaults mean you don't have to repeat known SKU data on every booking.

Sync patterns

Same as Inventory: the source of truth is upstream.

• Push from PIM / ERP. Your system pushes catalog updates to Carriyo as products change.
• Connector sync. Some connectors (Shopify, Magento) sync product data alongside orders.
• API import. Bulk-import on initial setup; per-SKU updates via the API thereafter.

Multi-merchant catalogs

On multi-merchant tenants, each merchant has its own catalog. The same SKU can exist for two merchants with different metadata: a wholesale-channel SKU might have different pricing or customs categorization than its retail equivalent.

Cross-merchant catalog sharing isn't a built-in concept. Catalogs are per-merchant.

How it fits with other modules

• Orders. Line items reference SKUs; catalog resolves them.
• Shipping. Items on a shipment inherit catalog metadata.
• Inventory. Inventory tracks quantities of SKUs; catalog describes them.
• Account model. Catalogs are per-merchant.