API: Import

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 tieback 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

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

Response (example)

1
{
2
  "ok": true
3
}

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

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

Response (example)

1
{
2
  "ok": true
3
}

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 tieback product fields. Must be called before validation.

Request

1
{
2
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001",
3
  "_column_mapping": {
4
    "sku": "sku",
5
    "name": "name.en",
6
    "weight_kg": "attributes.weight_kg"
7
  }
8
}

Response (example)

1
{
2
  "ok": true
3
}

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

1
{
2
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001"
3
}

Response (example)

1
{
2
  "ok": true
3
}

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

1
{
2
  "_job_id": "j1a2c3d4-0000-0000-0000-000000000001"
3
}

Response (example)

1
{
2
  "ok": true
3
}

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.