> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://tieback.io/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server. # API: Import > Import product data programmatically through the four-stage pipeline: create a job, stage rows and mappings, validate, and commit. > **Programmatic access — early access** > > The > > **tie*back*** > > 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 > > **tie*back*** > > to enable API credentials for your workspace. ## What It Does The Import API moves product data into **tie*back*** 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. | Stage | Purpose | | --------------- | ------------------------------------------------------------------------------ | | **1. Job** | Open an import job for the target workspace and record the source file name. | | **2. Stage** | Submit parsed rows and define how source columns map to product fields. | | **3. Validate** | Check every staged row for required fields, data types, and identifier format. | | **4. Commit** | Apply valid rows to the catalogue, creating or updating products. | ## Who It's For Developers building automated data pipelines that feed product data into **tie*back*** 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 ```json { "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001", "_file_name": "products_export_2026.csv", "_idempotency_key": "import-2026-02-20-001" } ``` #### Response (example) ```json { "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. --- ## 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 ```json { "_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) ```json { "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 **tie*back*** product fields. Must be called before validation. #### Request ```json { "_job_id": "j1a2c3d4-0000-0000-0000-000000000001", "_column_mapping": { "sku": "sku", "name": "name.en", "weight_kg": "attributes.weight_kg" } } ``` #### Response (example) ```json { "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. --- ## 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 ```json { "_job_id": "j1a2c3d4-0000-0000-0000-000000000001" } ``` #### Response (example) ```json { "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. --- ## 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 ```json { "_job_id": "j1a2c3d4-0000-0000-0000-000000000001" } ``` #### Response (example) ```json { "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 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. ## Related Docs * [Product Import](/product-module/product-import) * [API: Products](/api-reference/api-products) * [API: Bulk Updates](/api-reference/api-bulk-updates) * [API: Credentials](/api-reference/api-credentials)