About the Product Import API in general
-
Trax’ Product API enables its clients to send new products to Trax or to update already existing products in the Trax database.
-
Product updates sent via API to Trax will NOT be automatically added to Trax Product Database, but need to undergo a review process.
-
Product data should be added to a file to be sent as part of the corresponding POST request (see below).
-
Supported file formats: Excel, CSV, ZIP.
-
The ZIP file needs to contain either 1 Excel or 1 CSV file - multiple Excels or CSVs within a ZIP file are not supported.
-
-
The Excel/CSV should contain the following fields:
-
Product name
-
EAN code
-
Brand name
-
Manufacturer
-
Client category
-
Client Sub-Category
-
Product type
-
Container type
-
Size
-
UOM
-
Pack type
-
Units
-
Width mm
-
Height mm
-
Depth mm
-
1 - Front Image Name/URL
-
2 - Left Image Name/URL
-
3 - Top Image Name/URL
-
7 - Back Image Name/URL
-
8 - Right Image Name/URL
-
9 - Bottom Image Name/URL
-
Trax Product UUID
-
Status
-
Rejection/Deactivation reason
-
Additional attributes added to the project by Trax
-
-
Important notes on the above excel/csv fields:
-
Status can be either of the following values according to the request:
-
active (for activating a pending or deactivated or rejected product)
-
inactive (for deactivating an active product)
-
rejected (for rejecting a product)
-
-
When requesting deactivation or rejection of a product, you can provide a reason in the Rejection/Deactivation field
-
Additional attributes added by Trax to the project can be also included in the file, in this case the column name should match the additional attribute's name.
-
Files will be validated, during this validation it will only be checked if all rows of the file contain values for the following fields:
-
Product name
-
Brand name
-
Client category
-
Client Sub-Category
-
-
Rows failing this validation will be added to an error file, and Trax will only review the valid rows.
-
-
Adding product images can be done
- either by adding image URLs to the corresponding image fields in the CSV or Excel - when using this option, make sure that the image file(s) is (are) publicly available!,
-
or by adding the images to the ZIP file - in this case the corresponding image fields in the CSV/Excel need to contain the image name (without the extension).
-
Product update (regardless of sending 1 combined request or separate ones for validation and db upsert) is an async process, ie. the response contains a job ID which can be used to poll the API to get all available data incl. the status for the given upload.
Product Import API
Endpoints
Product updates to Trax
Upload details
Source and error file
POST
Product updates to Trax
Aim: To enable Clients to upload a file containing product data to Trax.
Supported protocol: HTTP
POST <host>/api/v4/<project>/products/import/suggestions
Ex. https://services.traxretail.com/api/v4/myproject/products/import/suggestions
Route
Request
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Request Body
file*
Excel/CSV/ZIP file with the product data as described above
Job ID in json format
Response
GET
Upload Details
Aim: To enable Clients to poll the APi to get data about an uploaded file and hence to primarily check the processing status of the file.
Route
Supported protocol: HTTP
POST <host>/api/v4/<project>/products/import/suggestions/details/<jobID>
Ex. https://services.traxretail.com/api/v4/myproject/products/import/details/63bc1722ed53e6d3e7cfc2e8
Request
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Request Param:
jobID*
ID added to the response of a file upload request
Response
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Request Param:
The response is provided in json format containing the following fields:
fileName
Source file name with extension.
importedBy
Email address of the uploader via UI, in case of API-upload the constant value: api-user
started
Timestamp when the file has been uploaded
status
Upload status as follows:
queued - initial status upon successful file upload, indicates that the file is ready for the validation
validating - indicates that the file's data is being validated
validated - indicates that validation could be completed and data are ready to be imported into the SAPI database
importing - indicated that the validated data are being imported into the SAPI database
imported - indicates that the the import process is completed and hence the data are added to the SAPI database
failed - terminal status, indicates that the file could not be processed.
parsed
Number of rows parsed by the API
total
Total number of rows as available in the source file as a result of the parsing process
errored
Total number of rows with errors
fileId
ID of the source file (mongo object ID)
errorId
ID of the file with errors if available (mongo object ID)
message
Additional information that belongs to the status
{
"fileName": "product_import_demo.xlsx",
"importedBy": "api-user",
"started": "2023-10-10T14:55:23.041Z",
"status": "imported",
"parsed": 2,
"total": 2,
"errored": 1,
"fileId": "652565dbd48b4b00072f232e",
"errorId": "652565e2d48b4b00072f2367",
"message": ""
}
Response example
GET
Source and error file
Aim: To enable Clients to poll the APi to get data about an uploaded file and hence to primarily check the processing status of the file.
Route
Supported protocol: HTTP
POST <host>/api/v4/<project>/products/import/suggestions/file/<fileID>
Ex. https://services.traxretail.com/api/v4/myproject/products/import/file/63bc1776aa849663db977fce
Request
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Request Param:
fileID*
Source or error file ID as provided in the response to a GET upload details request.
Response
-
Error: File in CSV format
-
Source file: as provided in the upload request (ie. CSV or Excel or ZIP)