Products

The Products resource represents items in your catalogue. Products are scoped to a merchant within your tenant and may be referenced by shipments, orders, returns, and inventory records.

Identifiers

Carriyo supports three ways to identify a product:

  • product_id — Assigned by Carriyo when the product is created. Unique within a tenant. Use this when you have stored the Carriyo identifier alongside your own.
  • product_ref — Your reference for the product. We recommend keeping this unique within a merchant so it can be used as a reliable lookup key.
  • sku — Stock keeping unit. SKU is not enforced as unique, so lookups by SKU return an array of matching products.

Listing Products

The GET /products endpoint is backed by Elasticsearch and supports:

  • Free-text search across sku , barcode , product_ref , description , hs_code , manufacturer_id , and material_composition
  • Filters on merchant , product_id , sku , barcode , product_ref , and status — repeat any filter parameter to match multiple values
  • Sorting by sku , barcode , product_ref , description , hs_code , or manufacturer_id , in ascending or descending direction
  • Pagination via page (zero-indexed) and page_size (max 250)

The response returns the matching page of products together with the total count, so you can drive paging UIs and report-style queries from the same endpoint.

Cross-Border Attributes

For shipments crossing customs borders, certain product attributes are typically required by carriers and customs:

  • hs_code — Harmonised System code for customs classification
  • origin_country — ISO 3166-1 alpha-2 country code
  • material_composition — e.g., "100% cotton" — relevant for textile classification
  • dangerous_goods — set true if the product is classified as dangerous goods
  • battery — supply material_type and packing_type if the product contains batteries
  • manufacturer_id — manufacturer reference, required by some carriers in certain destinations

Custom Metadata

Use carriyo_metadata to attach arbitrary name/value pairs to a product when the standard fields don't capture the attribute you need. These values are preserved in the product record and can be referenced in automation rules and downstream integrations.

Bulk Operations

For larger catalogues, two bulk operations are available:

  • Bulk create/update ( POST /products/{merchant_id}/bulk/import ) — submit up to 500 products in a single request. Each item is processed independently and the response reports per-item outcomes.
  • Bulk delete ( DELETE /products/{merchant_id}/bulk ) — deletes all products for the merchant. Large catalogues may require multiple invocations; the more_items_available flag in the response indicates whether to re-invoke.