API reference

Products API

The Carriyo Products API manages your product catalog. Products are referenced by shipments, orders, returns, and inventory, so keeping the catalog 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 https://carriyo.com/docs/api/idempotency/ for the full contract.

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

Products

The Products resource represents the items in your catalog. Products are scoped to a merchant within your tenant and are referenced by shipments, orders, returns, and inventory.

Identifiers. A product can be addressed in three ways:

product_id: assigned by Carriyo when the product is created. Unique within the tenant and never changed. Use it on paths; a create request that carries one is rejected.
product_ref: your reference. Required on create and unique within the merchant, so it is a reliable lookup key. Changing a product's product_ref, or deleting the product, releases the old value for another product to use.
sku: stock keeping unit. Not unique, so a lookup by SKU returns an array.

Reading by product_ref is strongly consistent. A product is found by its reference immediately after it is created or its reference is changed. The same applies when a bulk import matches existing products by reference.

Concurrent writes. Two requests that write the same product, or the same reference, at the same moment cannot both succeed. The one that loses receives 409 and should be retried.

Listing products. GET /products is served by the search index and supports free-text search, exact filters, sorting and paging across merchants. The index is updated shortly after each write, so a product written a moment ago may not be listed yet. Use the lookups by product_id or product_ref when you need the latest state.

Cross-border attributes. Carriers and customs typically need these fields on items that cross a border:

hs_code: Harmonized System code for customs classification.
origin_country: ISO 3166-1 alpha-2 country code.
material_composition: for example 100% cotton; used in textile classification.
dangerous_goods: true when the product is classified as dangerous goods.
battery: material_type and packing_type when the product contains batteries.
manufacturer_id: manufacturer reference, required by some carriers in certain destinations.

Custom data. carriyo_metadata holds free name/value pairs. custom_attributes holds values for the custom attributes defined for products on your account and is validated against them.

Bulk operations. Two operations cover larger catalogs:

Bulk import (POST /products/{merchant_id}/bulk/import): up to 500 products per request, each created or updated independently, with a result per item.
Bulk delete (DELETE /products/{merchant_id}/bulk): deletes up to 500 of the merchant's products per call. Repeat while more_items_available is true.

11 operations · 0 objects

get/products

List products

Returns a page of products matching the filters, search string and sort order you supply.

Scope. Without merchant, the page covers every merchant your credentials can access. Repeat merchant to narrow it. A merchant outside your access is dropped from the selection; when none remains, the request is rejected.

Filters. Each filter is an exact match on the field of the same name. Repeat a filter to match any of its values.

Search. search_string matches product_id exactly and searches sku, barcode, product_ref, description, category, hs_code, manufacturer_id, material_composition, product_type and variant_parent_ref.

Paging. page starts at 0 and page_size is at most 250. A query can reach the first 10,000 results only; narrow the filters to see the rest.

Freshness. The list is served by the search index, which is updated shortly after each write.

Query parameters

Name	Type	Required	Description
search_string	string	No	Free-text search across `product_id`, `sku`, `barcode`, `product_ref`, `description`, `category`, `hs_code`, `manufacturer_id`, `material_composition`, `product_type` and `variant_parent_ref`.
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.
product_ref	string	No	Filter by your reference (`product_ref`). 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.
inventory_key	string	No	Filter by inventory key. Repeat the parameter to match multiple values.
category	string	No	Filter by category. Repeat the parameter to match multiple values.
product_type	string	No	Filter by product type. Repeat the parameter to match multiple values.
variant_parent_ref	string	No	Filter variants by the `product_ref` of their parent. Repeat the parameter to match multiple values.
status	string	No	Filter by product status. Repeat the parameter to match multiple values.
sort_by	string	No	Field to sort the results by. Unsorted when omitted.
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

200The matching page of products and the total match count.Schema: product-list-response

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

400Schema: middleware-error-response

The request was rejected. One of:

sort_by is not one of the listed fields.
page_size is above 250, or page or page_size is not a number.
page and page_size together reach past the first 10,000 results.

errorstring
A human-readable message describing why the request failed.
errorCodestring
A short machine-readable name for the failure, such as BadRequest or Forbidden.

403None of the requested merchant values is within your credentials' merchant access.Schema: middleware-error-response

errorstring
A human-readable message describing why the request failed.
errorCodestring
A short machine-readable name for the failure, such as BadRequest or Forbidden.

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

post/products/{merchant_id}

Create product

Creates a product for the merchant in the path and returns the stored record with its Carriyo-assigned product_id.

What to send. product_ref is required and must not be in use by another product of the merchant. Do not send product_id; Carriyo generates it. A merchant in the body is ignored in favor of the path. Omitted fields take their defaults: product_type SIMPLE, status ACTIVE, do_not_place_above and do_not_place_below false.

Product types. A VARIANT keeps variant_parent_ref and variant_attributes. A PACK keeps pack_components and must have at least one. Fields that belong to another type are dropped without an error. variant_parent_ref and pack_components[].product_ref are stored as given and not checked against the catalog, so the products they name may be created later.

Custom attributes. custom_attributes is validated against the custom attributes defined for products on your account. An unknown attribute, or a value outside an attribute's allowed list, is rejected.

Idempotency. Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See https://carriyo.com/docs/api/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 https://carriyo.com/docs/api/idempotency/.

Request body

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

product_refstring
Your reference for the product. Required on create and on PUT, and unique within the merchant. Changing it releases the old value for reuse by another product.
skustring
Stock keeping unit. Not unique, so several products may share one; use product_ref or product_id to identify a product.
inventory_keystring
The inventory key the product's stock is tracked by, typically the barcode or GTIN. Products sharing a key share stock. Cannot be cleared with PATCH.
product_typestring
The kind of product: SIMPLE is standalone, VARIANT is one variation of a parent, PACK is a bundle of other products. Defaults to SIMPLE. Fields that belong to another type are dropped.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not checked against the catalog, so the parent may be created later.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size; keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with a quantity each. Required for PACK products and dropped for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin. Must be a code Carriyo recognizes.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details, for example 100% cotton. Used in 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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product. Defaults to ACTIVE.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items. Defaults to false.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items. Defaults to false.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs for attributes the standard fields do not cover.
custom_attributescustom-attributes
Values for the custom attributes defined for products on your account. An unknown attribute, or a value outside an attribute's allowed list, is rejected.

Responses

200Product created.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

400Schema: error-response

The request was rejected. One of:

product_ref is missing or blank.
another product of the merchant already has this product_ref.
product_id is present in the body.
status is not ACTIVE, INACTIVE or DELETED.
the body is not valid JSON, or a value is outside its type or enum.
origin_country is not a two-letter ISO 3166 code Carriyo recognizes.
product_type is PACK and pack_components is empty or has a component without product_ref.
a pack component has a quantity that is not above 0, or two components share a product_ref.
product_type is VARIANT and variant_attributes has a key other than color or size.
custom_attributes names an attribute not defined for products, carries a value the attribute does not allow, or the account is not subscribed to custom attributes.

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

409The write lost a race with another write to the same product or product_ref. Nothing was stored; retry the request.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

get/products/{merchant_id}

Search products by SKU

Returns every product of the merchant with the given sku. SKU is not unique, so the response is 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

200The products carrying the SKU, one or more.

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. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

400The sku query parameter is missing.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant carries this sku.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

get/products/{merchant_id}/{product_id}

Get product by ID

Returns one 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.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

put/products/{merchant_id}/{product_id}

Update product

Replaces the whole product record and returns the result.

What happens. Every field takes the value in the body. A field you omit is cleared, or reset to its default as on create. creation_date and creation_source are kept. That includes inventory_key: omit it and the product no longer carries one, while its inventory positions stay stored under the key.

What to send. product_ref is required. It may be a new value as long as no other product of the merchant uses it; the old value is released for reuse. product_id in the body is optional and must equal the path value.

Product types and custom attributes. The rules of Create product apply to the new record.

Use Patch product to change a few fields and keep the rest.

Idempotency. Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See https://carriyo.com/docs/api/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 https://carriyo.com/docs/api/idempotency/.

Request body

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

product_refstring
Your reference for the product. Required on create and on PUT, and unique within the merchant. Changing it releases the old value for reuse by another product.
skustring
Stock keeping unit. Not unique, so several products may share one; use product_ref or product_id to identify a product.
inventory_keystring
The inventory key the product's stock is tracked by, typically the barcode or GTIN. Products sharing a key share stock. Cannot be cleared with PATCH.
product_typestring
The kind of product: SIMPLE is standalone, VARIANT is one variation of a parent, PACK is a bundle of other products. Defaults to SIMPLE. Fields that belong to another type are dropped.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not checked against the catalog, so the parent may be created later.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size; keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with a quantity each. Required for PACK products and dropped for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin. Must be a code Carriyo recognizes.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details, for example 100% cotton. Used in 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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product. Defaults to ACTIVE.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items. Defaults to false.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items. Defaults to false.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs for attributes the standard fields do not cover.
custom_attributescustom-attributes
Values for the custom attributes defined for products on your account. An unknown attribute, or a value outside an attribute's allowed list, is rejected.

Responses

200The updated product.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

400Schema: error-response

The request was rejected. One of:

product_ref is missing or blank.
another product of the merchant already has this product_ref.
product_id in the body differs from the path.
status is not ACTIVE, INACTIVE or DELETED.
the body is not valid JSON, or a value is outside its type or enum.
origin_country is not a two-letter ISO 3166 code Carriyo recognizes.
product_type is PACK and pack_components is empty or has a component without product_ref.
a pack component has a quantity that is not above 0, or two components share a product_ref.
product_type is VARIANT and variant_attributes has a key other than color or size.
custom_attributes names an attribute not defined for products, carries a value the attribute does not allow, or the account is not subscribed to custom attributes.

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

409The write lost a race with another write to the same product or product_ref. Nothing was stored; retry the request.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

patch/products/{merchant_id}/{product_id}

Patch product

Updates the fields present in the body and keeps every other field as it is.

Field rules.

product_ref: a new value replaces the current one and releases it for reuse by another product. An empty string is ignored; the reference cannot be removed.
sku: an empty string clears it.
inventory_key: a new value replaces the current one. An empty string is ignored.
variant_parent_ref: an empty string clears it.
carriyo_metadata: merged by name. A new name is added, an existing name takes the new value, and a null value removes the entry.
custom_attributes: merged by attribute name. A null value removes the attribute.
pack_components, variant_attributes, weight, dimension and battery: replaced as a whole.
product_id: optional and must equal the path value.

Product types and custom attributes. The rules of Create product apply to the merged record. Changing product_type to PACK therefore needs pack_components in the same request, unless the product already has them.

Idempotency. Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See https://carriyo.com/docs/api/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 https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: product-requestrequired

product_refstring
Your reference for the product. Required on create and on PUT, and unique within the merchant. Changing it releases the old value for reuse by another product.
skustring
Stock keeping unit. Not unique, so several products may share one; use product_ref or product_id to identify a product.
inventory_keystring
The inventory key the product's stock is tracked by, typically the barcode or GTIN. Products sharing a key share stock. Cannot be cleared with PATCH.
product_typestring
The kind of product: SIMPLE is standalone, VARIANT is one variation of a parent, PACK is a bundle of other products. Defaults to SIMPLE. Fields that belong to another type are dropped.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not checked against the catalog, so the parent may be created later.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size; keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with a quantity each. Required for PACK products and dropped for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin. Must be a code Carriyo recognizes.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details, for example 100% cotton. Used in 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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product. Defaults to ACTIVE.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items. Defaults to false.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items. Defaults to false.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs for attributes the standard fields do not cover.
custom_attributescustom-attributes
Values for the custom attributes defined for products on your account. An unknown attribute, or a value outside an attribute's allowed list, is rejected.

Responses

200The updated product.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

400Schema: error-response

The request was rejected. One of:

product_id in the body differs from the path.
status is not ACTIVE, INACTIVE or DELETED.
the body is not valid JSON, or a value is outside its type or enum.
another product of the merchant already has the new product_ref.
origin_country is not a two-letter ISO 3166 code Carriyo recognizes.
the merged record is a PACK whose pack_components is empty or has a component without product_ref.
a pack component has a quantity that is not above 0, or two components share a product_ref.
the merged record is a VARIANT whose variant_attributes has a key other than color or size.
custom_attributes names an attribute not defined for products, carries a value the attribute does not allow, or the account is not subscribed to custom attributes.

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

409The write lost a race with another write to the same product or product_ref. Nothing was stored; retry the request.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

delete/products/{merchant_id}/{product_id}

Delete product

Deletes the product and returns the record as it was.

What happens. The product's product_ref is released for reuse by another product. When no other product carries the product's inventory_key, the inventory positions held against that key are deleted too. The request has no body.

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, as it was before deletion.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

409The delete lost a race with another write to the same product or product_ref. Nothing was deleted; retry the request.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

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

Get product by product ref

Returns one product by your product_ref. The read is strongly consistent, so a product created or re-referenced a moment ago is found.

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.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_ref.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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 and returns the record as it was.

What happens. The product_ref is released for reuse by another product. When no other product carries the product's inventory_key, the inventory positions held against that key are deleted too. The request has no body.

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, as it was before deletion.Schema: product-response

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier. Unique within the tenant and never changed.
product_refstring
Your reference for the product. Unique within the merchant.
skustring
Stock keeping unit. Not unique.
inventory_keystring
The inventory key the product's stock is tracked by.
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
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin.
manufacturer_idstring
Manufacturer reference.
material_compositionstring
Material details, for example 100% cotton.
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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs attached to the product.
custom_attributescustom-attributes
Values of the custom attributes defined for products on your account.
creation_datestringformat: date-time
When the product was created (ISO 8601).
update_datestringformat: date-time
When the product was last updated (ISO 8601).
creation_sourcerequest-source
Which system or actor created the product.
update_sourcerequest-source
Which system or actor last updated the product.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

404No product of the merchant has this product_ref.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

409The delete lost a race with another write to the same product or product_ref. Nothing was deleted; retry the request.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

post/products/{merchant_id}/bulk/import

Bulk import products

Creates or updates up to 500 products in one request and reports a result for each item.

Matching. An item with product_id must match an existing product of the merchant; otherwise it is rejected. product_id is a lookup key only and is never written. An item without product_id is matched on product_ref, with a strongly consistent read. A matched product is updated with the field rules of Patch product. An unmatched item is created with the rules of Create product, so it needs product_ref.

Within the request. Items are de-duplicated on product_ref, or on product_id when no reference is given; a repeat is rejected with the reason Duplicate Item. sku plays no part in matching. variant_parent_ref and pack_components[].product_ref are stored unverified, so an item may name another item of the same request, in any order.

Results. The response has one entry per item, in request order, so entry n answers item n. result is created, updated or rejected, and reason carries the message. An item that lost a race with a concurrent write is rejected with a reason starting Processing failed:; resend that item.

Idempotency. Supports optional Idempotency-Key for safe retries after timeouts or other uncertain network outcomes. See https://carriyo.com/docs/api/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 https://carriyo.com/docs/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. Required on create and on PUT, and unique within the merchant. Changing it releases the old value for reuse by another product.
skustring
Stock keeping unit. Not unique, so several products may share one; use product_ref or product_id to identify a product.
inventory_keystring
The inventory key the product's stock is tracked by, typically the barcode or GTIN. Products sharing a key share stock. Cannot be cleared with PATCH.
product_typestring
The kind of product: SIMPLE is standalone, VARIANT is one variation of a parent, PACK is a bundle of other products. Defaults to SIMPLE. Fields that belong to another type are dropped.
Values:SIMPLEVARIANTPACK
variant_parent_refstring
The product_ref of the parent product. Applies to VARIANT products only. Stored as given and not checked against the catalog, so the parent may be created later.
variant_attributesobject
What distinguishes this variant from its siblings. Applies to VARIANT products only. Keys must be color or size; keys are lower-cased and values trimmed.
pack_componentspack-component[]
The products this pack is made of, with a quantity each. Required for PACK products and dropped for every other type.
descriptionstring
Human-readable product description.
barcodestring
Barcode, for example an EAN or UPC.
image_linkstring
URL of a product image.
hs_codestring
Harmonized System code for customs classification.
origin_countrystring
ISO 3166-1 alpha-2 code of the country of origin. Must be a code Carriyo recognizes.
manufacturer_idstring
Manufacturer reference. Required by some carriers in certain destinations.
material_compositionstring
Material details, for example 100% cotton. Used in 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 with no physical shipment.
non_returnableboolean
Whether the product is excluded from returns.
statusstring
Lifecycle status of the product. Defaults to ACTIVE.
Values:ACTIVEINACTIVEDELETED
weightweight
A weight with its unit.
dimensiondimension
Outer dimensions with their unit.
do_not_place_aboveboolean
Stacking constraint: the item must not be placed above other items. Defaults to false.
do_not_place_belowboolean
Stacking constraint: the item must not be placed below other items. Defaults to false.
carriyo_metadatacarriyo-metadata[]
Free name/value pairs for attributes the standard fields do not cover.
custom_attributescustom-attributes
Values for the custom attributes defined for products on your account. An unknown attribute, or a value outside an attribute's allowed list, is rejected.
product_idstring
Carriyo-assigned identifier of an existing product to update. Lookup key only; a product_id that matches no product is rejected rather than created. Omit it to match on product_ref or to create a product.

Responses

200One result per item. Rejections are reported here, not as an error status.

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

product_idstring
The product_id of the product created or updated. For a rejected item, the product_id the item carried, if any.
skustring
The sku the item carried, echoed back.
product_refstring
The product_ref the item carried, echoed back.
resultstring
created when a new product was created, updated when an existing product was updated, rejected on failure.
Values:createdupdatedrejected
reasonstring
The outcome message. For a rejected item, why it was rejected.
itemproduct-response
The stored product for a created or updated item. null for a rejected item.

400Schema: error-response

The request was rejected. One of:

the array has more than 500 items.
the body is not valid JSON, or a value is outside its type or enum. The whole request is rejected; problems with one item come back as rejected entries instead.

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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

delete/products/{merchant_id}/bulk

Bulk delete products

Deletes up to 500 of the merchant's products in one call and reports the counts. This cannot be undone.

What happens. Each product's product_ref is released for reuse. Inventory positions are deleted for every inventory key that no remaining product carries. Products are deleted in parallel; a product that cannot be deleted is counted in failed_count and left in place.

Repeating. When more_items_available is true, 500 products were found and more may remain. Call again until it is false. The request has no body.

Outcome. Failures do not produce an error status. result is rejected and reason explains when the operation could not run at all; otherwise result is accepted and the counts tell you what happened.

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

200The counts for this call.Schema: bulk-delete-response

deleted_countinteger
Number of products deleted in this call.
attempted_countinteger
Number of products found and attempted in this call, at most 500.
failed_countinteger
Number of products that could not be deleted and were left in place.
reasonstring
A message summarizing the outcome.
resultstring
accepted when the operation ran, even if some products failed to delete. rejected when it could not run at all; reason says why.
Values:acceptedrejected
more_items_availableboolean
Whether more products may remain. Call again until false.

403Your credentials' merchant access does not cover merchant_id.Schema: error-response

errorsstring[]
Error messages describing what went wrong, one entry per line of the underlying message.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.
timestampstringformat: date-time
When Carriyo built the error response.

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>