top of page

  1. Trax’ Product API enables its clients to request an update of their Products and Brands database by sending

    1. new products (SKUs or POSMs) to Trax,

    2. changes of already existing products,

    3. new DVCs (alternative designs) to Trax,

    4. changes of already existing DVCs (alternative designs).

  2. Product update requests sent via API to Trax will NOT be automatically added to Trax Product Database, but will be stored in an interim database and will undergo a review process.

  3. Product update 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.​

  4. Product data should be added to a file to be sent as part of the corresponding POST request (see below).

    1. Supported file formats: Excel, CSV, ZIP.

    2. The ZIP file needs to contain either 1 Excel or 1 CSV file - multiple Excels or CSVs within a ZIP file are not supported.

  5. The CSV/Excel file can contain the following fields (mandatory fields are marked with asterisk *):

    1. Product English name - String(150)

    2. Product local name* - String(150)

    3. Product short name - String(150)

    4. EAN code - String(21)

    5. Brand name - String(150)

    6. Brand local name* - String(150)

    7. Manufacturer name - String(150)

    8. Manufacturer local name* - String(150)

    9. Client category* - String(150)

    10. Client sub-category - String(100)

    11. Product type* - List, accepted values: SKU, POS, POSM, DVC

    12. Action - List, accepted values: Create, Update, Deactivate

    13. Deactivation reason - String(100)

    14. Container type - String(150)

    15. Size - Float

    16. Measurement unit - String(20)

    17. Pack type - String(100)

    18. Units - Integer

    19. Width mm - Integer

    20. Height mm - Integer

    21. Depth mm - Integer

    22. 1 - Front Image Name/URL - String(500)

    23. 2 - Left Image Name/URL - String(500)

    24. 3 - Top Image Name/URL - String(500)

    25. 7 - Back Image Name/URL - String(500)

    26. 8 - Right Image Name/URL - String(500)

    27. 9 - Bottom Image Name/URL - String(500)

    28. Trax product ID - Integer

    29. Trax product UUID - Char(36)

    30. Start date - Date, format: YYYY-MM-DD

    31. End date - Date, format: YYYY-MM-DD

    32. Alternative Design Name - String(150)

    33. <Additional Attribute Name> - String(150)

  6. ​CSVs/Excels will be validated:

    1. If the file contains column headers other than the ones described above, the entire file upload will be rejected.​

    2. Rows will also be validated according to the validation rules described in the list above. Rows failing this validation will be added to an error file, and Trax will only review the valid rows.​ The error file's ID will be added to the upload details response and can be downloaded by using the GET file endpoint (see below)

  7. Adding product images can be done

    1. 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!,

    2. 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 Import API

Product Update: Use cases

  1. Add new products

    1. Add for the Action field the value Create

    2. Add for the Product type field the value SKU

    3. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide any other data available at your end

      3. NOT to provide values for the fields Trax product ID and Trax product UUID used to identify existing products in Trax' Product and Brands database

  2. Change product attributes/images

    1. Add for the Action field the value Update

    2. Add for the Product type field the value SKU

    3. Add for the field Trax product ID or Trax product UUID the Trax ID/UUID (accordingly) of the product the change(s) need(s) to be applied for.  

    4. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category),

      2. to provide any other data available at your end.

  3. Deactivate products

    1. Add for the Action field the value Deactivate

    2. Add for the Product type field the value SKU

    3. Add for the Trax product ID or Trax product UUID the Trax ID/UUID (accordingly) of the product which should be deactivated.

    4. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide a deactivation reason if available at your end,

      3. to provide any other data available at your end.

  4. Add new POSMs

    1. Add for the Action field the value Create

    2. Add for the Product type field the value POS or POSM

    3. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide any other data available at your end

      3. NOT to provide values for the fields Trax product ID and Trax product UUID used to identify existing products in Trax' Product and Brands database

  5. Change POSM attributes/images

    1. Add for the Action field the value Update

    2. Add for the Product type field the value POS or POSM

    3. Add for the field Trax product ID or Trax product UUID the Trax ID/UUID (accordingly) of the POSM the change(s) need(s) to be applied for.

    4. Please make sure

      1. to provide values to all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide any other data available at your end.

  6. Deactivate POSMs

    1. Add for the Action field the value Deactivate

    2. Add for the  to the Product type field the value POS or POSM

    3. Add for the field Trax product ID or Trax product UUID the Trax ID/UUID (accordingly) of the POSM which should be deactivated.

    4. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide a deactivation reason if available at your end,

      3. to provide any other data available at your end.

  7. Add new DVCs

    1. Add for the Action field the value Create

    2. Add for the Product type field the value DVC

    3. Please make sure

      1. to provide values for all other mandatory fields (Product local name, Brand local name, Manufacturer local name, Client category)

      2. to provide values for the fields Alternative design name and at least start date and end date also if availble,

      3. to provide any other data available at your end

      4. to provide a value for either of the fields Trax product ID and Trax product UUID used to identify products in Trax' Product and Brands database the DVC needs to be assigned to

Product Update: File Examples

  1. Supported file formats: Excel, CSV, ZIP.

  2. When sending CSVs, please make sure that the values are separated by semicolons ";" and not by comas ","!

  3. We have the following recommendations regarding what file format to use: 

    1. CSV/Excel: product updates without images or with image links
      In the latter case, please make sure​

      1. to make the image urls publicly available

      2. and add the entire URL to the corresponding image field in the CSV/Excel. 

    2. ZIP: product updates with images directly added to the compressed file.
      When using this format, please make sure

      1. to add only 1 single CSV/Excel to the compressed filed,

      2. to add only the file names without extension (!) to the corresponding row in the CSV/Excel,

      3. to include all image files in the compressed file.

  4. Below you can find samples for all 3 supported file formats.

  5. Important notes:

    1. Excel/CSV & Excel in the ZIP:​

      1. Files can contain multiple request types (add new product, change product attributes, add DVC etc.).​

      2. The below sample files contain examples for each request type:
        Row #1: Add new product​​
        Row #2: Change product attribute
        Row #3: Deactivate a product
        Row #4: Add new POSM
        Row #5: Change POSM
        Row #6: Deactivate POSM
        RoW #7: Add new DVC

    2. Excel/CSV: Row #1 (Add new product) shows an example of how to add a public image URL.

    3. ZIP: Row #1 (Add new product) of the Excel shows an example of how to add an image contained in the compressed file.

POST Uploads - To enable Clients to upload a file containing product data to Trax.

​

GET Details - 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

​

GET Files - 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.

Endpoints

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.

​

Supported protocol: HTTPS

GET <host>/api/v4/<project>/products/import/suggestions/file/<fileID>

Ex. https://services.traxretail.com/api/v4/myproject/products/import/suggestions/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)

GET Source or 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.

​

Supported protocol: HTTPS

GET <host>/api/v4/<project>/products/import/suggestions/details/<importId>

Ex. https://services.traxretail.com/api/v4/myproject/products/import/suggestions/details/63bc1722ed53e6d3e7cfc2e8

 

Request

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

Request Param:

importID* ID added to the response of a file upload request

 

Response

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 for the import

importing - indicated that the validated data are being imported

imported - indicates that the the import process is completed and hence the data are added to 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)

uuid - Unique identifier of the import

​message - Additional information that belongs to the status, eg. a header name which could not recognised (not listed above)

​

Example for the response

{
    "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",

    "uuid": "80eaa39b-2a84-44f3-a8bc-8cac3210bffd",
    "message": ""
}

GET Upload Details

POST Uploads

Aim: To enable Clients to upload a file containing product data to Trax.

​

Supported protocol: HTTPS

POST <host>/api/v4/<project>/products/import/suggestions

Ex. https://services.traxretail.com/api/v4/myproject/products/import/suggestions

 

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

​

Response

importId - in json format

bottom of page