Skip to main content

​
What It Does

The Import API provides RPCs for the full product import lifecycle: creating a job, submitting rows, mapping columns, validating data, and committing the import.

​
Who It’s For

Developers building automated data pipelines that feed product data into MintID from external systems.

​
create_import_job

​
What it does

Creates a new import job for the specified brand. The job starts in a draft state and accepts rows and mappings before validation and commit.

​
Request

{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_file_name": "products_export_2026.csv",
  "_idempotency_key": "import-2026-02-20-001"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have admin access to the specified brand.
  • Invalid input — missing required fields or duplicate idempotency key.

​
bulk_upsert_import_rows

​
What it does

Submits parsed rows to an existing import job. Rows are upserted by row number within the job — resubmitting the same row number replaces the previous data.

​
Request

{
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001",
  "_rows_json": [
    { "row_number": 1, "raw_row": { "sku": "WIDGET-001", "name": "Blue Widget" } },
    { "row_number": 2, "raw_row": { "sku": "WIDGET-002", "name": "Red Widget" } }
  ]
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have access to the specified job.
  • Invalid input — rows are malformed or missing required fields (row_number, raw_row).

​
set_import_mapping

​
What it does

Defines how source CSV columns map to MintID product fields. Must be called before validation.

​
Request

{
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001",
  "_column_mapping": {
    "sku": "sku",
    "name": "name.en",
    "weight_kg": "attributes.weight_kg"
  }
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have access to the specified job.
  • Invalid input — column mapping is not a valid JSON object.

​
validate_import_job

​
What it does

Runs server-side validation on all rows in the job. Each row is checked for required fields, data types, value-set compliance, and identifier format. Must be called before commit.

​
Request

{
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have access to the specified job.
  • Invalid input — job has no rows or no column mapping set.

​
commit_import_job

​
What it does

Commits the import, creating or updating products for all valid (non-excluded) rows. Each row is processed independently — a failure on one row does not affect others. The job must be validated before committing.

​
Request

{
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access for this operation.
  • Invalid input — request is malformed or cannot be processed.

​
Typical Workflow

  1. Call create_import_job with the brand ID and file name.
  2. Call bulk_upsert_import_rows with parsed row data.
  3. Call set_import_mapping to define column-to-field mappings.
  4. Call validate_import_job to check all rows.
  5. Call commit_import_job to apply the import.

​
Limits & Notes

  • All import RPCs require authentication with admin role.
  • Each row is processed independently during commit.
  • Idempotency keys prevent duplicate job creation.
  • Validation must complete before commit is allowed.

​
FAQ

Can I update an existing row after submission? Yes. Call bulk_upsert_import_rows again with the same row numbers — rows are upserted by row number. What file formats are supported? The API accepts pre-parsed JSON row data. CSV parsing is handled client-side before calling the API.