Products import tasks
Summary of products imports endpoints
- POST /admin/api/ecommerce/v1/products_imports — create a new products import task.
- GET /admin/api/ecommerce/v1/products_imports — list all products import tasks.
- GET /admin/api/ecommerce/v1/products_imports/:id — get a single products import task.
- PUT /admin/api/ecommerce/v1/products_imports/:id/queue — queue a products import for processing.
- DELETE /admin/api/ecommerce/v1/products_imports/:id — delete a products import task.
The product import object
Attributes
file_url— full URL to the file to be imported. Supported formats: XLSX, ODS, CSV.language— language of the file to be imported. Only one language can be imported at a time. It applies to all products related text fields, such as name, description, variant names, category names, etc.overwrite_existing— if set totrue, first existing product will be overwritten when products with the providedmatch_keyfield are found. When product is not found, a new product will be created. Default value isfalse.match_key- identifier to use for matching imported products. Matching products are updated instead of creating a new product. Supported values areidandsku. Defaults toid.validate_mapping— if set totrue, the file will be validated against the provided mapping. Default value isfalse. This parameter is accepted only on create action.mapping— key value pairs of the file columns and the product attributes they map to. The key is the column index (starting from0) and the value is the product attribute name and must be in the list ofsupported_attributes. If the value isnull, the column will be ignored.
Read only attributes
completed_at— timestamp when the import was completed.created_at— timestamp when the import was created.detected_data— preview of the detected data in the file. The preview is limited to 4 rows.failed_items— number of rows that failed to import.failure_reason_details— detailed information about the failure. Object can provide following keys:key— error key.message— error message.line— row number.
failure_reason— reason for the failure.id— unique identifier for the import.imported_products— number of products imported.processed_items— number of rows processed.started_at— timestamp when the import was started.status— status of the import. Possible values are:created— the import task is created.queued— the import task is added to the async queue.started— the import task is started.finished— the import task is finished.failed— the import task failed.cancelled— the import task was cancelled by the user.
supported_attributes— list of supported detectable and importable attributes.total_items— total number of rows detected in the file when the import was created.updated_at— timestamp when the import was updated.
Create a new products import task
POST /admin/api/ecommerce/v1/products_imports
Attributes
See above for a detailed description of the request payload.
Example request
POST http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports
{
"file_url": "https://example.com/products-import.xlsx",
"language": "en",
"overwrite_existing": false
}
Example response
{
"id": 1,
"status": "created",
"started_at": null,
"completed_at": null,
"total_items": 5,
"processed_items": 0,
"failed_items": 0,
"imported_products": null,
"file_url": "https://example.com/products-import.xlsx",
"language": "en",
"overwrite_existing": false,
"detected_data": [
{
"column": "ID",
"values": [
"6554",
"6557",
"6558",
"6559"
]
},
{
"column": "Parent ID",
"values": [
"",
"6554",
"6554",
"6554"
]
},
{
"column": "Row type",
"values": [
"matrix",
"variant",
"variant",
"variant"
]
},
{
"column": "Product code",
"values": [
"",
"",
"",
""
]
},
{
"column": "Name",
"values": [
"My product with variants",
"My product with variants",
"My product with variants",
"My product with variants"
]
},
{
"column": "Variant attributes",
"values": [
"",
"Size: S, Color: Black",
"Size: S, Color: Red",
"Size: M, Color: Black"
]
},
{
"column": "Description",
"values": [
"",
"",
"",
""
]
},
{
"column": "Meta description",
"values": [
"",
"",
"",
""
]
},
{
"column": "Price",
"values": [
10.0,
11.0,
11.0,
12.0
]
},
{
"column": "Sale price",
"values": [
5.0,
5.0,
5.0,
5.0
]
},
{
"column": "Effective price",
"values": [
5.0,
5.0,
5.0,
5.0
]
},
{
"column": "Currency",
"values": [
"EUR",
"EUR",
"EUR",
"EUR"
]
},
{
"column": "Stock",
"values": [
null,
null,
null,
null
]
},
{
"column": "Reserved quantity",
"values": [
0,
0,
0,
0
]
},
{
"column": "Available stock",
"values": [
null,
null,
null,
null
]
},
{
"column": "Status",
"values": [
"Live",
"Live",
"Live",
"Live"
]
},
{
"column": "Product is variant",
"values": [
"False",
"True",
"True",
"True"
]
},
{
"column": "Categories",
"values": [
"Sale, Clothing",
"",
"",
""
]
},
{
"column": "Image",
"values": [
null,
null,
null,
null
]
},
{
"column": "Length",
"values": [
null,
null,
null,
null
]
},
{
"column": "Width",
"values": [
null,
null,
null,
null
]
},
{
"column": "Height",
"values": [
null,
null,
null,
null
]
},
{
"column": "Dimension unit",
"values": [
"m",
"m",
"m",
"m"
]
},
{
"column": "Weight",
"values": [
10.0,
100.0,
10.0,
10.0
]
},
{
"column": "Weight unit",
"values": [
"kg",
"kg",
"kg",
"kg"
]
},
{
"column": "Created at",
"values": [
"2023-12-22T17:04:56.000+00:00",
"2023-12-22T17:05:35.000+00:00",
"2023-12-22T17:05:35.000+00:00",
"2023-12-22T17:05:35.000+00:00"
]
},
{
"column": "Updated at",
"values": [
"2023-12-22T17:06:15.000+00:00",
"2023-12-22T17:06:05.000+00:00",
"2023-12-22T17:06:05.000+00:00",
"2023-12-22T17:06:05.000+00:00"
]
}
],
"mapping": {
"0": "id",
"1": "parent_id",
"2": null,
"3": "sku",
"4": "name",
"5": "variant_attributes_text",
"6": "description",
"7": "og_description",
"8": "price",
"9": "sale_price",
"10": null,
"11": null,
"12": "stock",
"13": "reserved_quantity",
"14": null,
"15": "status",
"16": "product_is_variant",
"17": "categories",
"18": null,
"19": "length",
"20": "width",
"21": "height",
"22": null,
"23": "weight",
"24": null,
"25": null,
"26": null
},
"failure_reason": null,
"failure_reason_details": null,
"created_at": "2023-12-22T17:16:40.000Z",
"updated_at": "2023-12-22T17:17:01.336Z",
"supported_attributes": {
"id": {
"type": "integer",
"read_only": true,
"title": "ID"
},
"parent_id": {
"type": "integer",
"read_only": true,
"title": "Parent ID"
},
"sku": {
"type": "string",
"title": "Product code"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "URL slug"
},
"description": {
"type": "string",
"title": "Description"
},
"og_description": {
"type": "string",
"title": "Meta description"
},
"price": {
"type": "decimal",
"title": "Price"
},
"sale_price": {
"type": "decimal",
"title": "Sale price"
},
"stock": {
"type": "integer",
"title": "Stock"
},
"reserved_quantity": {
"type": "integer",
"title": "Reserved quantity"
},
"status": {
"type": "enum",
"title": "Status",
"enum_values": [
{
"title": "Draft",
"value": "draft"
},
{
"title": "Live",
"value": "live"
}
]
},
"length": {
"type": "decimal",
"title": "Length"
},
"width": {
"type": "decimal",
"title": "Width"
},
"height": {
"type": "decimal",
"title": "Height"
},
"weight": {
"type": "decimal",
"title": "Weight"
},
"product_is_variant": {
"type": "boolean",
"title": "Product is variant"
},
"variant_attributes_text": {
"type": "key_set",
"title": "Variant attributes"
},
"categories": {
"type": "array",
"title": "Categories"
}
}
}
Retrieve all products import tasks
GET /admin/api/ecommerce/v1/products_imports
Query string parameters
per_page— orders per response (default:50; maximum:250).page— requested page (default:1).
Filter attributes
Read more about filters.
- Object
products_importattributes:id,status,started_at,completed_at,total_items,processed_items,created_at,updated_at.
Example request
GET http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports
Retrieve a single products import task
GET /admin/api/ecommerce/v1/products_imports/:id
Example request
GET http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1
Example response
{
"id": 1,
"status": "finished",
"started_at": "2023-12-22T17:18:00.336Z",
"completed_at": "2023-12-22T17:18:02.336Z",
"total_items": 5,
"processed_items": 0,
"failed_items": 0,
"imported_products": 1,
"file_url": "https://example.com/products-import.xlsx",
"language": "en",
"overwrite_existing": false,
"detected_data": [
{
"column": "ID",
"values": [
"6554",
"6557",
"6558",
"6559"
]
},
{
"column": "Parent ID",
"values": [
"",
"6554",
"6554",
"6554"
]
},
{
"column": "Row type",
"values": [
"matrix",
"variant",
"variant",
"variant"
]
},
{
"column": "Product code",
"values": [
"",
"",
"",
""
]
},
{
"column": "Name",
"values": [
"My product with variants",
"My product with variants",
"My product with variants",
"My product with variants"
]
},
{
"column": "Variant attributes",
"values": [
"",
"Size: S, Color: Black",
"Size: S, Color: Red",
"Size: M, Color: Black"
]
},
{
"column": "Description",
"values": [
"",
"",
"",
""
]
},
{
"column": "Price",
"values": [
10.0,
11.0,
11.0,
12.0
]
},
{
"column": "Sale price",
"values": [
5.0,
5.0,
5.0,
5.0
]
},
{
"column": "Effective price",
"values": [
5.0,
5.0,
5.0,
5.0
]
},
{
"column": "Currency",
"values": [
"EUR",
"EUR",
"EUR",
"EUR"
]
},
{
"column": "Stock",
"values": [
null,
null,
null,
null
]
},
{
"column": "Reserved quantity",
"values": [
0,
0,
0,
0
]
},
{
"column": "Available stock",
"values": [
null,
null,
null,
null
]
},
{
"column": "Status",
"values": [
"Live",
"Live",
"Live",
"Live"
]
},
{
"column": "Product is variant",
"values": [
"False",
"True",
"True",
"True"
]
},
{
"column": "Categories",
"values": [
"Sale, Clothing",
"",
"",
""
]
},
{
"column": "Image",
"values": [
null,
null,
null,
null
]
},
{
"column": "Length",
"values": [
null,
null,
null,
null
]
},
{
"column": "Width",
"values": [
null,
null,
null,
null
]
},
{
"column": "Height",
"values": [
null,
null,
null,
null
]
},
{
"column": "Dimension unit",
"values": [
"m",
"m",
"m",
"m"
]
},
{
"column": "Weight",
"values": [
10.0,
100.0,
10.0,
10.0
]
},
{
"column": "Weight unit",
"values": [
"kg",
"kg",
"kg",
"kg"
]
},
{
"column": "Created at",
"values": [
"2023-12-22T17:04:56.000+00:00",
"2023-12-22T17:05:35.000+00:00",
"2023-12-22T17:05:35.000+00:00",
"2023-12-22T17:05:35.000+00:00"
]
},
{
"column": "Updated at",
"values": [
"2023-12-22T17:06:15.000+00:00",
"2023-12-22T17:06:05.000+00:00",
"2023-12-22T17:06:05.000+00:00",
"2023-12-22T17:06:05.000+00:00"
]
}
],
"mapping": {
"0": "id",
"1": "parent_id",
"2": null,
"3": "sku",
"4": "name",
"5": "variant_attributes_text",
"6": "description",
"7": "price",
"8": "sale_price",
"9": null,
"10": null,
"11": "stock",
"12": "reserved_quantity",
"13": null,
"14": "status",
"15": "product_is_variant",
"16": "categories",
"17": null,
"18": "length",
"19": "width",
"20": "height",
"21": null,
"22": "weight",
"23": null,
"24": null,
"25": null
},
"failure_reason": null,
"failure_reason_details": null,
"created_at": "2023-12-22T17:16:40.000Z",
"updated_at": "2023-12-22T17:18:01.336Z",
"supported_attributes": {
"id": {
"type": "integer",
"read_only": true,
"title": "ID"
},
"parent_id": {
"type": "integer",
"read_only": true,
"title": "Parent ID"
},
"sku": {
"type": "string",
"title": "Product code"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "URL slug"
},
"description": {
"type": "string",
"title": "Description"
},
"og_description": {
"type": "string",
"title": "Meta description"
},
"price": {
"type": "decimal",
"title": "Price"
},
"sale_price": {
"type": "decimal",
"title": "Sale price"
},
"stock": {
"type": "integer",
"title": "Stock"
},
"reserved_quantity": {
"type": "integer",
"title": "Reserved quantity"
},
"status": {
"type": "enum",
"title": "Status",
"enum_values": [
{
"title": "Draft",
"value": "draft"
},
{
"title": "Live",
"value": "live"
}
]
},
"length": {
"type": "decimal",
"title": "Length"
},
"width": {
"type": "decimal",
"title": "Width"
},
"height": {
"type": "decimal",
"title": "Height"
},
"weight": {
"type": "decimal",
"title": "Weight"
},
"product_is_variant": {
"type": "boolean",
"title": "Product is variant"
},
"variant_attributes_text": {
"type": "key_set",
"title": "Variant attributes"
},
"categories": {
"type": "array",
"title": "Categories"
}
}
}
Queue a products import for processing
PUT /admin/api/ecommerce/v1/products_imports/:id/queue
Example request
PUT http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1/queue
Example response
{
"id": 1,
"status": "queued",
"started_at": null,
"completed_at": null,
"total_items": 5,
"processed_items": 0,
"failed_items": 0,
"imported_products": null,
"file_url": "https://example.com/products-import.xlsx",
"language": "en",
"overwrite_existing": false,
...
}
Delete a products import task
DELETE /admin/api/ecommerce/v1/products_imports/:id
Example request
DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1
Example response
Status: 204 No Content