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.

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. Either sku or product_ref is required to identify the product within your catalogue.

Returns the created product, including the Carriyo-assigned product_id.

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.

Request body

Content type: application/jsonSchema: product-requestrequired

product_refstring
Your reference for the product. Recommended to be unique within a merchant.
skustring
Stock keeping unit.
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.
product_refstring
Your reference for the product.
skustring
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.

tenantstring
The tenant identifier.
merchantstring
The merchant the product belongs to.
product_idstring
The Carriyo-assigned product identifier.
product_refstring
Your reference for the product.
skustring
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.
product_refstring
Your reference for the product.
skustring
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.

Use PATCH to update only a subset of fields.

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.

Request body

Content type: application/jsonSchema: product-requestrequired

product_refstring
Your reference for the product. Recommended to be unique within a merchant.
skustring
Stock keeping unit.
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.
product_refstring
Your reference for the product.
skustring
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.

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.

Request body

Content type: application/jsonSchema: product-requestrequired

product_refstring
Your reference for the product. Recommended to be unique within a merchant.
skustring
Stock keeping unit.
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.
product_refstring
Your reference for the product.
skustring
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.
product_refstring
Your reference for the product.
skustring
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.
product_refstring
Your reference for the product.
skustring
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.
product_refstring
Your reference for the product.
skustring
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 (accepted or rejected) for each item, in the same order.

Limits

Maximum 500 items per request.

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.

Request body

Content type: application/jsonrequired

product_refstring
Your reference for the product. Recommended to be unique within a merchant.
skustring
Stock keeping unit.
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

200Per-item processing results.

productIdstring
The Carriyo-assigned product ID, if assigned.
skustring
productRefstring
resultstring
Outcome for this item.
Values:acceptedrejected
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>