API Reference

API: Import

Programmatic access — early access

The

tieback

API is available to selected workspaces during early access. Endpoints in production today are authenticated with an authenticated session. Standalone API-key access is being onboarded per workspace. Contact

tieback

to enable API credentials for your workspace.

What It Does

The Import API moves product data into tieback through a four-stage pipeline. Nothing is written to your catalogue until the final stage, so an import can be inspected, corrected, and re-staged before it takes effect.

StagePurpose
1. JobOpen an import job for the target workspace and record the source file name.
2. StageSubmit parsed rows and define how source columns map to product fields.
3. ValidateCheck every staged row for required fields, data types, and identifier format.
4. CommitApply valid rows to the catalogue, creating or updating products.

Who It’s For

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

Stage 1: Job

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.

Stage 2: Stage

Staging has two parts: submitting the rows, and describing how their columns map to product fields. Both must be complete before validation.

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.

Stage 3: Validate

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.

Stage 4: Commit

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 operations 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.