Search
Voog.com
Search
Voog.com

Products import tasks

Summary of products imports endpoints

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 to true, first existing product will be overwritten when products with the provided match_key field are found. When product is not found, a new product will be created. Default value is false.
  • match_key - identifier to use for matching imported products. Matching products are updated instead of creating a new product. Supported values are id and sku. Defaults to id.
  • validate_mapping — if set to true, the file will be validated against the provided mapping. Default value is false. 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 from 0) and the value is the product attribute name and must be in the list of supported_attributes. If the value is null, 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

Example
Copy
POST /admin/api/ecommerce/v1/products_imports

Attributes

See above for a detailed description of the request payload.

Example request

Example
Copy
POST http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports
Example
Copy
{
  "file_url": "https://example.com/products-import.xlsx",
  "language": "en",
  "overwrite_existing": false
}

Example response

Example
Copy
{
  "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"
    }
  }
}
Show all

Retrieve all products import tasks

Example
Copy
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_import attributes: id, status, started_at, completed_at, total_items, processed_items, created_at, updated_at.

Example request

Example
Copy
GET http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports

Retrieve a single products import task

Example
Copy
GET /admin/api/ecommerce/v1/products_imports/:id

Example request

Example
Copy
GET http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1

Example response

Example
Copy
{
  "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"
    }
  }
}
Show all

Queue a products import for processing

Example
Copy
PUT /admin/api/ecommerce/v1/products_imports/:id/queue

Example request

Example
Copy
PUT http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1/queue

Example response

Example
Copy
{
  "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

Example
Copy
DELETE /admin/api/ecommerce/v1/products_imports/:id

Example request

Example
Copy
DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products_imports/1

Example response

Example
Copy
Status: 204 No Content
Products import tasks
Summary of products imports endpoints
The product import object
Create a new products import task
Retrieve all products import tasks
Retrieve a single products import task
Queue a products import for processing
Delete a products import task
Product
Create online store
Create web page
Create blog
Integrations
All Features
Partners
Company
About Voog
Affiliate program
Blog
Support
Help Centre
Contact Support
Follow Us
Facebook
Twitter
Instagram
©2025 – hello@voog.com
Language In English
Eesti keeles Auf Deutsch Latviešu Suomeksi По-русски In nederlands En français Em português Lietuvių kalba
Cookie settings Privacy Policy Terms & Conditions