Bulk Uploads

Bulk uploads are a way to create large sets of products in the system via a file upload, often a csv file.

Csv file can define various fields of product and its variants along with property sets.

CSV¶

Headers¶

Apart from the above headers, there could be dynamic headers based on the product variants and their associated property sets.

Variant Headers¶

If a product has multiple variants, csv can be provided with headers that indicate the variant attributes. If the product has variants for colors, sweep size and power consumption, headers could be Variant #; color, Variant #; sweep size(mm) and Variant #; power consumption(watts)

Property Sets Headers¶

Property sets are three kinds names tables, lists and media. CSV file can capture those arbitrary data points too.

If the product needs to define a property set table named details with keys rated speed, no of blades and guarantee and Rated frequency, the columns can be provided as Property Set Table #; details #; rated speed(m³/min), Property Set Table #; details #; no of blades, Property Set Table #; details #; guarantee(years) and Property Set Table #; details #; Rated frequency(Hz)

If the product needs to define a property set list named Notable Features, the column can be named as Property Set List #; Notable Features and the list items can be separated by #;.

If the product needs to define a property set media named Gallery, the column can be named as Property Set Media #; Gallery and the list items can be separated by #;. The expected values for this property set will be public url images.

Example CSV¶

Here is an example csv for reference

API¶

Bulk Upload Object¶

Below is the json representation of the bulk upload object, followed by a data table

{
  "status": "success",
  "data": {
    "id": "32e03a84-50e5-41d7-83af-03bc804eb871",
    "started_at": null,
    "ended_at": null,
    "progress": null,
    "status": "draft",
    "output": null,
    "created_at": "2023-06-15T10:29:05.828Z",
    "updated_at": "2023-06-15T10:29:05.833Z",
    "processor_name": "file_content_echo_processor",
    "file": {
      "id": "a668784f-3fd0-4c3e-8ba0-d0b2ba2cfd9c",
      "key": "ejnvr7oe4tfbdwr45yerk3c4dxfg",
      "content_type": "text/csv",
      "byte_size": 174
    }
  }
}

All Fields¶

Status State Machine¶

status field represents file processing status of the bulk upload

Possible values: draft, in_progress, success and failure. Below diagram shows possible transitions on the product status.

graph LR
  A[draft] --> |update_progress| B[in_progress];
  B --> |succeed| C[success];
  B --> |fail| D[failure]  

List Bulk Uploads¶

GET /api/platform/v1/bulk_uploads

The result set is paginated and can be controlled by page and per_page query parameters

curl 'http://localhost:3000/api/platform/v1/bulk_uploads' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer jLyAZh5cfv4h_IORVzYy5fTt9ZMZCmvx153qrJRkPYU' \
    -H 'Content-Type: application/json'         

Get Bulk Upload¶

GET /api/platform/v1/bulk_uploads/{id}

The result contains the bulk upload record.

curl 'http://localhost:3000/api/platform/v1/bulk_uploads/32e03a84-50e5-41d7-83af-03bc804eb871' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer jLyAZh5cfv4h_IORVzYy5fTt9ZMZCmvx153qrJRkPYU' \
    -H 'Content-Type: application/json'         

{
  "status": "success",
  "data": {
    "id": "32e03a84-50e5-41d7-83af-03bc804eb871",
    "started_at": null,
    "ended_at": null,
    "progress": null,
    "status": "draft",
    "output": null,
    "created_at": "2023-06-15T10:29:05.828Z",
    "updated_at": "2023-06-15T10:29:05.833Z",
    "processor_name": "file_content_echo_processor",
    "file": {
      "id": "a668784f-3fd0-4c3e-8ba0-d0b2ba2cfd9c",
      "key": "ejnvr7oe4tfbdwr45yerk3c4dxfg",
      "content_type": "text/csv",
      "byte_size": 174
    }
  }
}

Create Product¶

POST /api/platform/v1/bulk_uploads

curl --location 'http://localhost:3000/api/platform/v1/bulk_uploads' \
      --header 'Authorization: Bearer 9owpfhMyKqVr2TLlfspx1wKyi713uf17KFvlMoOJORk' \
      --form 'processor_name="catalog_csv_upload_processor"' \
      --form 'file=@"/path/to/file"'

{
  "status": "failure",
  "data": [{
    "attribute_name": "bulk_upload_processor",
    "messages": ["Bulk upload processor class is not defined"]
  }]
}