Bulk Create Products

Creates or updates 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.

SecurityOAuth2-Production or OAuth2-Demo

Request

path Parameters

merchant_id

required

string

The merchant identifier the product belongs to.

header Parameters

x-api-key required	string Your Carriyo API key for authentication.
tenant-id required	string Your unique tenant identifier in Carriyo.

Request Body schema: application/json
required

Array

product_ref	string Your reference for the product. Recommended to be unique within a merchant.
sku	string Stock keeping unit.
description	string Human-readable product description.
barcode	string Barcode (e.g., EAN, UPC).
image_link	string URL to a product image.
hs_code	string Harmonised System code. Often required for cross-border shipments.
origin_country	string ISO 3166-1 alpha-2 country code of origin.
manufacturer_id	string Manufacturer reference. Required by some carriers in certain destinations.
material_composition	string Material details (e.g., "100% cotton"). Relevant for textile customs classification.
category	string Product category.
dangerous_goods	boolean Whether the product is classified as dangerous goods.
	object (Battery) Battery details. Usually required for cross-border shipments containing batteries.
digital	boolean Whether the product is a digital good (no physical shipment).
non_returnable	boolean Whether the product is excluded from returns.
status	string (Status) Lifecycle status of the product. Enum: "ACTIVE" "INACTIVE" "DELETED"
	object (Weight)
	object (Dimension)
do_not_place_above	boolean Stacking constraint — must not be placed above other items.
do_not_place_below	boolean Stacking constraint — must not be placed below other items.
	Array of objects (Carriyo Metadata) Custom name/value pairs for storing additional product attributes.

Responses

200

Per-item processing results.

400

Invalid request (e.g., too many items).

post/products/{merchant_id}/bulk/import

Request samples

application/json

[{"product_ref": "string",
"sku": "string",
"description": "string",
"barcode": "string",
"image_link": "string",
"hs_code": "string",
"origin_country": "string",
"manufacturer_id": "string",
"material_composition": "string",
"category": "string",
"dangerous_goods": true,
"battery": {"material_type": "lithium_metal",
"packing_type": "contained_in_equipment"
},
"digital": true,
"non_returnable": true,
"status": "ACTIVE",
"weight": {"value": 0,
"unit": "kg"
},
"dimension": {"width": 0,
"height": 0,
"depth": 0,
"unit": "cm"
},
"do_not_place_above": true,
"do_not_place_below": true,
"carriyo_metadata": [{"name": "string",
"value": "string"
}
]
}
]

Response samples

application/json

[{"productId": "string",
"sku": "string",
"productRef": "string",
"result": "accepted",
"reason": "string",
"item": {"tenant": "string",
"merchant": "string",
"product_id": "string",
"product_ref": "string",
"sku": "string",
"description": "string",
"barcode": "string",
"image_link": "string",
"hs_code": "string",
"origin_country": "string",
"manufacturer_id": "string",
"material_composition": "string",
"category": "string",
"dangerous_goods": true,
"battery": {"material_type": "lithium_metal",
"packing_type": "contained_in_equipment"
},
"digital": true,
"non_returnable": true,
"status": "ACTIVE",
"weight": {"value": 0,
"unit": "kg"
},
"dimension": {"width": 0,
"height": 0,
"depth": 0,
"unit": "cm"
},
"do_not_place_above": true,
"do_not_place_below": true,
"carriyo_metadata": [{"name": "string",
"value": "string"
}
],
"creation_date": "2019-08-24T14:15:22Z",
"update_date": "2019-08-24T14:15:22Z",
"creation_source": {"source_type": "string",
"source_id": "string",
"api_pattern": "string",
"request_type": "string",
"system_log_identifier": "string"
},
"update_source": {"source_type": "string",
"source_id": "string",
"api_pattern": "string",
"request_type": "string",
"system_log_identifier": "string"
}
}
}
]