top of page

Product Import v2

Product Import Functionality​
Product import is an asynchronous process.
When an import request is submitted, the API returns an importId. That identifier can then be used to poll the import status and fetch import metadata, including parsing progress, validation errors, and final result.
Supported protocol: HTTPS


Product Matching and Upsert Rules
The import logic decides whether to update an existing product or create a new one based on the following fields:

  • Dedicated Customer Product ID

  • Product UUID

The expected behavior is:

  1. If the request row contains an existing Customer Product ID, the system updates that product. In this case, the product UUID is ignored.

  2. If the Customer Product ID is not provided, but the product UUID is provided, the system updates the product identified by the UUID.

  3. If no product is found by the provided Customer Product ID, but a product is found by the provided UUID, the system updates that product and also sets its Customer Product ID to the provided value.

  4. If the import row contains a Customer Product ID but no product UUID, and no existing product is found for that Customer Product ID, the system creates a new product and assigns the provided Customer Product ID to it.

  5. If neither the Customer Product ID nor the product UUID is provided, the system creates a new product.

 

Import Processing Behavior
Each row in the uploaded file is validated.

  • Valid rows are upserted into the database.

  • Invalid rows are written into an error file.

There is also a validation-only flow, where the file is checked but no records are imported.
General Error Responses

  • 404: Import not found by the provided import ID

  • 429: Rate limit exceeded, too many requests

  • 409: Import does not belong to the provided project

​

General Success Responses

  • 200: OK

  • 201: Created

  • 204: No Content

 

API Endpoints
Name    Method    Endpoint
Import a File    POST    /api/v5/<project_name>/entity/products/import
Validate an Import File    POST    /api/v5/<project_name>/entity/products/import/validate
Run a Previously Validated Import    POST    /api/v5/<project_name>/entity/products/import/run/<import_id>
Get Import Details by ID    GET    /api/v5/<project_name>/entity/products/import/details/<import_id>
Delete an Import    DELETE    /api/v5/<project_name>/entity/products/import/<import_id>
Download Import Errors    GET    /api/v5/<project_name>/entity/products/import/download/error/<import_id>

​

Import a File
Endpoint
POST <host>/api/v5/<project_name>/entity/products/import
Headers
Authorization: Auth-Token {project auth token}
Authentication token provided by Trax.
Request Body

  • file (required): Excel file containing product data

Response (HTTP 201)

{

  "importId": "6a4e2f9963aa10000704b20d"

}

​

Errors

  • 400: Missing file or file not attached

  • 404: Invalid route

  • 500: Server error

​

Validate an Import File

Endpoint

POST <host>/api/v5/<project_name>/entity/products/import/validate

 

Headers

Authorization: Auth-Token {project auth token}

Response (HTTP 200)

The request and response are the same as for the import endpoint. The difference is that records are only validated, not imported.

Use this endpoint to:

  • verify whether the uploaded records are valid

  • retrieve validation errors before running the actual import

 

Run a Previously Validated Import

Endpoint

POST <host>/api/v5/<project_name>/entity/products/import/run/<import_id>

Headers

Authorization: Auth-Token {project auth token}

Only validated imports that contain at least one valid row can be run. Validated imports with no valid rows are rejected.

Response (HTTP 200)

This starts the actual import step after validation. Only valid records are imported.

Errors

  • 400: Import is not in validated status or all rows are errored

 

Get Import Details by ID

Endpoint

GET <host>/api/v5/<project_name>/entity/products/import/details/<import_id>

Purpose

Returns the current state and metadata of a previously submitted import.

Headers

Authorization: Auth-Token {project auth token}

Path Parameter

  • import_id: The import ID returned by the initial import request

Response (HTTP 200)

{

  "fileName": "v2-products(1).xlsx",

  "importedBy": "api-user",

  "started": "2026-07-08T10:38:51.403Z",

  "status": "imported",

  "parsed": 1,

  "total": 1,

  "errored": 1,

  "fileId": "6a4e28bbe7b64b00077f18fe",

  "errorId": "6a4e28c4e7b64b00077f19a5",

  "uuid": "3af69773-4262-4a12-bded-18725d5e3764",

  "importId": "6a4e28bb63aa10000704b125",

  "message": "", "projectName":

  "integ11",

  "type": "v2products"

}

 

Response Fields

  • fileName: Name of the source file

  • importedBy: User email that uploaded the file, or api-user for API uploads

  • started: Import start timestamp

  • status: Current import state

  • parsed: Number of parsed rows

  • total: Total number of rows in the source file

  • errored: Number of invalid rows

  • fileId: ID of the source file

  • errorId: ID of the generated error log file

  • uuid: Import UUID

  • importId: Import identifier

  • message: Additional import information

  • projectName: Name of the project

  • type: Import type, currently always v2products

 

Delete an Import

Endpoint

DELETE <host>/api/v5/<project_name>/entity/products/import/<import_id>

Headers

Authorization: Auth-Token {project auth token}

Purpose

Deletes import-related metadata and bookkeeping.

This does not revert changes already made by the import.

Response (HTTP 204)

  • 204: Deleted successfully

 

Download Import Errors

Endpoint

GET <host>/api/v5/<project_name>/entity/products/import/download/error/<import_id>

Purpose

Downloads the generated error file for a previous product import.

Headers

Authorization: Auth-Token {project auth token}

Path Parameter

  • import_id: The import ID returned by the initial import request

Response (HTTP 200)

Error file in .xlsx format.

 

Import Status Values

The status field in the import details response can contain the following values:

  • queued: Initial status after the request is accepted

  • validating: File validation is in progress

  • validated: Validation completed successfully

  • importing: Valid rows are being imported

  • imported: Import completed successfully

  • failed: Import failed

 

Typical Flow

  1. Upload a file with the import endpoint.

  2. Store the returned importId.

  3. Poll the import details endpoint until the status reaches a terminal state.

  4. If validation-only mode was used, call the run endpoint to start importing the validated rows.

  5. If needed, download the error file for invalid rows.

  6. Optionally delete the import metadata after processing is complete.

​

bottom of page