API reference

Products API

The Carriyo Products API manages your product catalogue. Products are referenced by shipments, orders, returns, and inventory, so keeping the catalogue up to date keeps downstream data accurate.

Idempotency

Write endpoints accept an optional Idempotency-Key request header for safe request replay when your integration retries after uncertain network outcomes. Replayed responses include Idempotent-Replayed: true. See Idempotency for the full contract.

Serverhttps://api.carriyo.comAuthOAuth 2.0 + API KeySpecproducts.yaml

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: for example "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.

11 operations · 0 objects

get/products

List products

Returns a paginated list of products that match the supplied filter, sort, and search criteria.

The list endpoint is backed by Elasticsearch and supports free-text search across product fields such as description, sku, barcode, product_ref, hs_code, manufacturer_id, and material_composition.

Filters are applied as exact term matches. Most filters can be repeated to match any of the supplied values.

Query parameters

Name	Type	Required	Description
search_string	string	No	Free-text search applied across `sku`, `barcode`, `product_ref`, `description`, `hs_code`, `manufacturer_id`, and `material_composition`.
merchant	string	No	Filter by merchant. Repeat the parameter to match multiple merchants.
product_id	string	No	Filter by Carriyo product ID. Repeat the parameter to match multiple values.
sku	string	No	Filter by SKU. Repeat the parameter to match multiple values.
barcode	string	No	Filter by barcode. Repeat the parameter to match multiple values.
product_ref	string	No	Filter by your reference (`product_ref`). Repeat the parameter to match multiple values.
status	string	No	Filter by product status.
sort_by	string	No	Field to sort the results by.
sort_direction	string	No	Sort direction. Defaults to `desc`.
page	integer	No	Page number, starting from 0. Defaults to 0.
page_size	integer	No	Number of results per page. Defaults to 10. Maximum 250.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200A paginated list of products.Schema: product-list-response

itemsproduct-response[]
The page of matching products.
totalinteger
Total number of products matching the query (across all pages).

Need the full machine-readable spec? Download the OpenAPI document →

post/products/{merchant_id}

Create product

Creates a new product for the specified merchant. product_ref is required and must be unique within the merchant. sku is optional and may be shared by several products, so it cannot be used to identify one.

product_id is not accepted in the request body — Carriyo generates it and it can never be changed afterwards. Supplying one is rejected with a 400.

Returns the created product, including the Carriyo-assigned product_id. Store it, or use product_ref, to address the product on later requests.

Idempotency

Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See Idempotency.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See [Idempotency](/api/idempotency/).

Request body

Content type: application/jsonSchema: product-create-requestrequired

product_refstring
Your reference for the product. Must be unique within a merchant. Mandatory when creating a product and when replacing one with PUT. On PATCH it may be changed but not removed — a blank value is ignored rather than clearing the field.
skustring
Stock keeping unit. Optional, and need not be unique — several products may share one, so it is descriptive only and cannot be used to identify a product. Use product_ref or product_id for that.
product_typestring
The kind of product. SIMPLE is a standalone product. VARIANT is one variation of a parent product, identified by variant_parent_ref and described by variant_attributes. PACK is a bundle of other products, listed in pack_components. Defaults to SIMPLE. Fields belonging to another type are ignored: a PACK drops variant_parent_ref and variant_attributes, and anything that is not a PACK drops pack_components.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not verified, so it may name a product created later — for example a parent and its variants sent in the same bulk import, in any order. Products are referenced by product_ref only; a parent cannot be named by its product_id.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size — any other key is rejected with a 400. Keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with the quantity of each. Required for PACK products and ignored for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode (e.g., EAN, UPC).
image_linkstring
URL to a product image.
hs_codestring
Harmonised System code. Often required for cross-border shipments.
origin_countrystring
ISO 3166-1 alpha-2 country code of origin.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details (e.g., "100% cotton"). Relevant for textile customs classification.
categorystring
Product category.
dangerous_goodsboolean
Whether the product is classified as dangerous goods.
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
Whether the product is a digital good (no physical shipment).
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
Stacking constraint: must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Custom name/value pairs for storing additional product attributes.

Responses

200Successfully created the product.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

400Invalid request payload.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

get/products/{merchant_id}

Search products by SKU

Returns all products belonging to the merchant that match the supplied sku. SKU is not guaranteed to be unique within a merchant, so this endpoint returns an array.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.

Query parameters

Name	Type	Required	Description
sku	string	Yes	The SKU to look up.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200List of matching products.

An array of product-response. Each item has the following fields:

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No products found.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

get/products/{merchant_id}/{product_id}

Get product by ID

Retrieves a single product by its Carriyo product_id.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_id	string	Yes	The Carriyo-assigned product identifier.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied ID.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

put/products/{merchant_id}/{product_id}

Update product

Replace the full product record. All fields are overwritten with the values in the request body; fields omitted from the body are cleared.

product_ref is required, and must stay unique within the merchant. The product is identified by the product_id in the path; product_id is immutable, so a different value in the body is rejected with a 400.

Use PATCH to update only a subset of fields.

Idempotency

Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See Idempotency.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_id	string	Yes	The Carriyo-assigned product identifier.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See [Idempotency](/api/idempotency/).

Request body

Content type: application/jsonSchema: product-create-requestrequired

product_refstring
Your reference for the product. Must be unique within a merchant. Mandatory when creating a product and when replacing one with PUT. On PATCH it may be changed but not removed — a blank value is ignored rather than clearing the field.
skustring
Stock keeping unit. Optional, and need not be unique — several products may share one, so it is descriptive only and cannot be used to identify a product. Use product_ref or product_id for that.
product_typestring
The kind of product. SIMPLE is a standalone product. VARIANT is one variation of a parent product, identified by variant_parent_ref and described by variant_attributes. PACK is a bundle of other products, listed in pack_components. Defaults to SIMPLE. Fields belonging to another type are ignored: a PACK drops variant_parent_ref and variant_attributes, and anything that is not a PACK drops pack_components.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not verified, so it may name a product created later — for example a parent and its variants sent in the same bulk import, in any order. Products are referenced by product_ref only; a parent cannot be named by its product_id.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size — any other key is rejected with a 400. Keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with the quantity of each. Required for PACK products and ignored for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode (e.g., EAN, UPC).
image_linkstring
URL to a product image.
hs_codestring
Harmonised System code. Often required for cross-border shipments.
origin_countrystring
ISO 3166-1 alpha-2 country code of origin.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details (e.g., "100% cotton"). Relevant for textile customs classification.
categorystring
Product category.
dangerous_goodsboolean
Whether the product is classified as dangerous goods.
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
Whether the product is a digital good (no physical shipment).
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
Stacking constraint: must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Custom name/value pairs for storing additional product attributes.

Responses

200The updated product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied ID.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

patch/products/{merchant_id}/{product_id}

Patch product

Partially updates the product record. Only fields supplied in the request body are updated; omitted fields retain their current values.

product_ref is not required here, since the product is identified by the product_id in the path. It may be changed by supplying a new value, but it cannot be removed — a blank value is ignored rather than clearing it. product_id is immutable, so a different value in the body is rejected with a 400.

Idempotency

Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See Idempotency.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_id	string	Yes	The Carriyo-assigned product identifier.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See [Idempotency](/api/idempotency/).

Request body

Content type: application/jsonSchema: product-requestrequired

product_refstring
Your reference for the product. Must be unique within a merchant. Mandatory when creating a product and when replacing one with PUT. On PATCH it may be changed but not removed — a blank value is ignored rather than clearing the field.
skustring
Stock keeping unit. Optional, and need not be unique — several products may share one, so it is descriptive only and cannot be used to identify a product. Use product_ref or product_id for that.
product_typestring
The kind of product. SIMPLE is a standalone product. VARIANT is one variation of a parent product, identified by variant_parent_ref and described by variant_attributes. PACK is a bundle of other products, listed in pack_components. Defaults to SIMPLE. Fields belonging to another type are ignored: a PACK drops variant_parent_ref and variant_attributes, and anything that is not a PACK drops pack_components.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not verified, so it may name a product created later — for example a parent and its variants sent in the same bulk import, in any order. Products are referenced by product_ref only; a parent cannot be named by its product_id.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size — any other key is rejected with a 400. Keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with the quantity of each. Required for PACK products and ignored for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode (e.g., EAN, UPC).
image_linkstring
URL to a product image.
hs_codestring
Harmonised System code. Often required for cross-border shipments.
origin_countrystring
ISO 3166-1 alpha-2 country code of origin.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details (e.g., "100% cotton"). Relevant for textile customs classification.
categorystring
Product category.
dangerous_goodsboolean
Whether the product is classified as dangerous goods.
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
Whether the product is a digital good (no physical shipment).
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
Stacking constraint: must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Custom name/value pairs for storing additional product attributes.

Responses

200The updated product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied ID.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

delete/products/{merchant_id}/{product_id}

Delete product

Deletes the product. The returned record reflects the product's state at the time of deletion.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_id	string	Yes	The Carriyo-assigned product identifier.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The deleted product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied ID.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

get/products/{merchant_id}/product-ref/{product_ref}

Get product by product ref

Retrieves a single product by your product_ref.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_ref	string	Yes	Your reference for the product (`product_ref`).

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied product_ref.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

delete/products/{merchant_id}/product-ref/{product_ref}

Delete product by product ref

Deletes the product identified by your product_ref.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.
product_ref	string	Yes	Your reference for the product (`product_ref`).

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The deleted product record.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Generated by Carriyo and immutable.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
product_typestring
The kind of product.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Present on VARIANT products only.
variant_attributesobject
What distinguishes this variant from its siblings. Present on VARIANT products only.
pack_componentspack-component[]
The products this pack is made of. Present on PACK products only.
descriptionstring
barcodestring
image_linkstring
hs_codestring
origin_countrystring
manufacturer_idstring
material_compositionstring
categorystring
dangerous_goodsboolean
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
non_returnableboolean
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
do_not_place_belowboolean
carriyo_metadatacarriyo-metadata[]
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
creation_sourcerequest-source
update_sourcerequest-source

404No product found for the supplied product_ref.Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

post/products/{merchant_id}/bulk/import

Bulk create products

Create or update multiple products in a single request. Each item in the request array is processed independently; the response array reports the outcome (created, updated, or rejected) for each item, in the same order.

Earlier versions returned result: "accepted" for both creates and updates. Update any integration that checks for accepted.

Matching an existing product

An item is matched to an existing product by product_id when one is supplied, otherwise by product_ref. A matched item is updated; an unmatched item is created, and creating requires product_ref.

product_id is a lookup key only — it is never written, so it cannot assign an ID to a new product. An item whose product_id matches no existing product is rejected rather than created. Each response entry returns the product_id of the product created or updated.

Items are de-duplicated within the request on product_ref (or on product_id when no ref is given). sku is not used for matching or de-duplication, since it need not be unique.

References between items

pack_components[].product_ref and variant_parent_ref are stored as given and not verified, so an item may reference another item in the same request regardless of the order they appear in — send a pack and its components, or a parent and its variants, in one call.

Both fields take a product_ref only. product_id cannot be used to reference a product, which is what makes order-independence possible: an ID is assigned by Carriyo and so cannot name a product that does not exist yet.

Limits

Maximum 500 items per request.

Idempotency

Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See Idempotency.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See [Idempotency](/api/idempotency/).

Request body

Content type: application/jsonrequired

An array of bulk-product-request. Each item has the following fields:

product_refstring
Your reference for the product. Must be unique within a merchant. Mandatory when creating a product and when replacing one with PUT. On PATCH it may be changed but not removed — a blank value is ignored rather than clearing the field.
skustring
Stock keeping unit. Optional, and need not be unique — several products may share one, so it is descriptive only and cannot be used to identify a product. Use product_ref or product_id for that.
product_typestring
The kind of product. SIMPLE is a standalone product. VARIANT is one variation of a parent product, identified by variant_parent_ref and described by variant_attributes. PACK is a bundle of other products, listed in pack_components. Defaults to SIMPLE. Fields belonging to another type are ignored: a PACK drops variant_parent_ref and variant_attributes, and anything that is not a PACK drops pack_components.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not verified, so it may name a product created later — for example a parent and its variants sent in the same bulk import, in any order. Products are referenced by product_ref only; a parent cannot be named by its product_id.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size — any other key is rejected with a 400. Keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with the quantity of each. Required for PACK products and ignored for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode (e.g., EAN, UPC).
image_linkstring
URL to a product image.
hs_codestring
Harmonised System code. Often required for cross-border shipments.
origin_countrystring
ISO 3166-1 alpha-2 country code of origin.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details (e.g., "100% cotton"). Relevant for textile customs classification.
categorystring
Product category.
dangerous_goodsboolean
Whether the product is classified as dangerous goods.
batterybattery
Battery details. Usually required for cross-border shipments containing batteries.
digitalboolean
Whether the product is a digital good (no physical shipment).
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
dimensiondimension
do_not_place_aboveboolean
Stacking constraint: must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Custom name/value pairs for storing additional product attributes.
product_idstring
Carriyo-assigned identifier of an existing product to update. Lookup key only — the value is never written, and a product_id that matches no product is rejected rather than created. Omit it to create a new product or to match on product_ref.

Responses

200Per-item processing results.

An array of bulk-create-update-response. Each item has the following fields:

productIdstring
The Carriyo-assigned product ID, if assigned.
skustring
productRefstring
resultstring
Outcome for this item, created when a new product was created, updated when an existing product was updated, rejected on failure.
Values:createdupdatedrejected
reasonstring
Reason for rejection, if result is rejected.
itemproduct-response

400Invalid request (e.g., too many items).Schema: error-response

errorstring
Error message describing what went wrong.
codestring
Error code for programmatic handling.

Need the full machine-readable spec? Download the OpenAPI document →

delete/products/{merchant_id}/bulk

Bulk delete products

Deletes all products for the specified merchant.

Warning: This operation is destructive and cannot be undone. The response indicates how many records were deleted, attempted, and failed, and whether more items remain. Large catalogues may require multiple invocations to fully clear.

Path parameters

Name	Type	Required	Description
merchant_id	string	Yes	The merchant identifier the product belongs to.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Bulk delete summary.Schema: bulk-delete-response

deleted_countinteger
Number of products successfully deleted.
attempted_countinteger
Number of products attempted in this invocation.
failed_countinteger
Number of products that failed to delete.
reasonstring
Failure reason, if applicable.
resultstring
Values:acceptedrejected
more_items_availableboolean
Whether more products remain to be deleted. Re-invoke until false.

Need the full machine-readable spec? Download the OpenAPI document →

Authentication

Every endpoint uses OAuth 2.0. Exchange your client credentials for an access token:

Get a token

curl -X POST 'https://api.carriyo.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'

Then send on every request

Authorization:Bearer <access-token>

tenant-id:<your-tenant-id>

x-api-key:<your-api-key>