Product Import Developer Guide

Prerequisites

In order to upload products, you must already have created your category taxonomy. For information on creating categories in the Product Agent UI, see Creating Categories.

Step 1: Postman Environment Setup

This part of the guide walks you through setting up a Postman environment to interact with the Product Agent API.

Create a new environment

Open Postman.
Click Environments in the sidebar.
Click + to create a new environment. Provide a name such as Product Agent - Prod.

Add the environment variables

Add the following variables to your environment.

access_token and the various defined IDs will be empty initially — they will be populated after making API calls.

Variable	Description	Example
`baseUrl`	Base URL for the API	`https://commerceos.aiagents.fabric.inc/api`
`authUrl`	Auth URL for the API	`https://commerceos.aiagents.fabric.inc`
`access_token`	Token used for authenticated requests	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`taxonomyWorkflowId`	ID of the taxonomy workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`attributeWorkflowId`	ID of the attribute workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`clientId`	Client ID provided by fabric. Used to create an access token	`svc_peyFD9BXPRrZymhjJtFuYr7L3Ai`
`clientSecret`	Client secret provided by fabric. Used to create an access token	`cw_GWve_9oI_aJKd-xcE7uuZJpr-WqfnRpDPznGNVI-fOc`
`domain`	Brand domain or identifier for scoping requests	`acme.com`

Step 2: Authentication

This part of the guide walks you through authenticating with the Product Agent API and storing your access token in Postman for future requests.

Create and set the access token

To authenticate, send a POST request to the token endpoint using your clientId and clientSecret. If you do not have these credentials, contact fabric support.

Tokens expire every 60 minutes.

curl --location '{{authUrl}}/platform/v1/auth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "grant_type": "client_credentials",
  "client_id": "{{clientId}}",
  "client_secret": "{{clientSecret}}"
  }'

Example Response:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzdmNfcGV5SkQ5DlhQUnRadW1oakp0RnVZcjdMbEFvIiwidHlwZ56UIkjnZpY2UiLCJjb21wYW55X2lkIjoiNjhiNzI3NjhlYzc1NGVjNzA2MjhkNTM5Iiwic2NvcGVzIjpbXSwiYnJhbmRfaWRzIjpbImNvbnRhaW5lcnN0b3JlLmNvbSJdLCJqdGkiOiI5MGQ3YjQ0NC03MTQxLTRhMDUtYWM4MC03OGJjZTMxZGI5OGUiLCJpYXQiOjE3NzQ1NDM2NDEsImV4cCI6MTc3NDU0NzI0MX0.kc9RQSirU2vIVl5oRTmuEBoaF1tmAeYB3KH87KAHJpM",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": ""
}

To automatically save the access_token for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("access_token", pm.response.json().access_token);

With this script, the access_token environment variable is automatically updated each time a request to the endpoint is made.

Step 3 (Optional): Import Attribute Definitions

You can optionally import attribute definitions for enrichment and mapping workflows. For information on creating attributes in the Product Agent UI, see Creating Attributes. This endpoint accepts a CSV file and creates an import job you can monitor using the returned import_id. We will save this to our environment as attributeWorkflowId.

Expected CSV columns for each attribute definition

Column	Required	Description
`attribute_name`	Yes	Attribute display name
`attribute_key`	No	Machine-readable key
`description`	Yes	Attribute description
`data_type`	No	Attribute data type
`scope`	No	Attribute scope
`enum_values`	No	Allowed values, pipe-delimited, for example `S\|M\|L`
`allow_ai_content`	No	Allow AI to generate values (`true` or `false`)
`source`	No	`MERCHANT` or `GOLD_STANDARD`
`guideline_reason`	No	Guidance for AI enrichment

Request

curl --location '{{baseUrl}}/v2/attributes/import' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--form 'file=@"/D:/Demo CSV files/attributes.csv"'

To automatically save the attributeWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("attributeWorkflowId", pm.response.json().import_id);

Example Response:

{
    "import_id": "e2716438-b763-4be8-82d2-36abe0cb92b1",
    "name": "attribute.csv",
    "status": "PENDING",
    "total_rows": 36,
    "processed_rows": 0,
    "created_count": 0,
    "updated_count": 0,
    "skipped_count": 0,
    "failed_count": 0,
    "input_filename": "attribute.csv",
    "input_file_url": null,
    "error_file_url": null,
    "error_message": null,
    "errors": [],
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-03-12T18:04:03.879876Z"
}

Check the import status

After the upload succeeds, use the saved attributeWorkflowId to check workflow status with:

curl --location '{{baseUrl}}/v2/attributes/import/{{attributeWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

Example Response:

{
    "import_id": "e2716438-b763-4be8-82d2-36abe0cb92b1",
    "name": "attribute.csv",
    "status": "COMPLETED",
    "total_rows": 36,
    "processed_rows": 36,
    "created_count": 35,
    "updated_count": 0,
    "skipped_count": 0,
    "failed_count": 1,
    "input_filename": "attribute_test.csv",
    "input_file_url": "https://product-agent-data-prod-ue2.s3.amazonaws.com/attribute/vessel/e2716438-b763-4be8-82d2-36abe0cb92b1.csv...",
    "error_file_url": "https://product-agent-data-prod-ue2.s3.amazonaws.com/attribute/vessel/e2716438-b763-4be8-82d2-36abe0cb92b1_errors.csv?X-...",
    "error_message": null,
    "errors": [
        "Row 35: invalid data_type 'BOOLREAN'"
    ],
    "started_at": "2026-03-12T18:04:03.998437Z",
    "completed_at": "2026-03-12T18:04:04.724584Z",
    "created_at": "2026-03-12T18:04:03.879876Z"
}

In this example, an error was flagged in the upload. You can resolve and publish updates to just that row or re-upload the entire file. Rows with errors are skipped. Once completed, you can review the attribute definitions you uploaded in the UI.

Log in to Product Agent.
In the left nav, click Settings. The Settings menu is displayed.
Click Taxonomy. The Categories tab is displayed by default.
Click Attributes.

Here you can review your attribute definitions.

Step 4: Import Your Products

After importing your categories and attribute definitions, you can upload products. During processing, products will be automatically mapped to your categories and aligned with the attribute definitions you’ve provided. This endpoint accepts a CSV file and creates a taxonomy workflow you can monitor using the returned workflow id. We will save this to our environment as taxonomyWorkflowId.

Expected CSV columns

Column	Required	Description
`title`	Yes	Product title
`breadcrumb`	Yes	Category breadcrumb path
`sku`	No	Product SKU
`category`	No	Product category
`description`	No	Product description
`images`	No	Image URLs
`attribute.*`	No	Custom attributes, for example `attribute.color`

Request

curl --location '{{baseUrl}}/v2/taxonomy-workflow?auto_enrich=true' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--form 'file=@"/D:/Demo CSV files/products.csv"'

To automatically save the taxonomyWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("taxonomyWorkflowId", pm.response.json().workflow_id);

Example Response:

{
  "id": "a1462a91-f733-45fe-993b-5d0353f33ee3",
  "brand_id": "268465dd-71f5-4179-959c-9bac01029451",
  "status": "PENDING",
  "workflow_type": "ATTRIBUTE_AND_CATEGORY_MAPPING",
  "import_document_path": "taxonomy-workflow/vessel/d6441888-f25d-4acb-8898-07808526ecdb/d6441888-f25d-4acb-8898-07808526ecdb_input.csv",
  "created_at": "2026-03-12T17:54:07.374339Z",
  "updated_at": "2026-03-12T17:54:07.374339Z",
  "total_category_mappings": 0,
  "total_attribute_mappings": 0,
  "workflow_id": "a1462a91-f733-45fe-993b-5d0353f33ee3",
  "workflow_status": "PENDING",
  "tenant_id": "268465dd-71f5-4179-959c-9bac01029451",
  "workflow_phase": "PRE_PROCESS",
  "domain": "acme.com",
  "total_items": 0,
  "processed_items": 0,
  "successful_items": 0,
  "failed_items": 0,
  "total_chunks": 0,
  "processed_chunks": 0,
  "input_file_id": "69b2fdbfd1dcca3911c666e6",
  "output_file_id": null,
  "error_file_id": null,
  "review_required": false,
  "review_task_id": null,
  "enrichment_workflow_id": null,
  "error_message": null
}

Check the import status

After the upload succeeds, use the saved taxonomyWorkflowId to check workflow status with:

curl --location '{{baseUrl}}/v2/taxonomy-workflow/{{taxonomyWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

Example Response:

{
    "id": "2345943b-91dd-4a3b-a923-b5c524049dcc",
    "brand_id": "268465dd-71f5-4179-959c-9bac01029451",
    "status": "COMPLETED",
    "workflow_type": "ATTRIBUTE_AND_CATEGORY_MAPPING",
    "import_document_path": "taxonomy-workflow/vessel/3c007843-d82b-4805-93f1-1afef9d1968e/3c007843-d82b-4805-93f1-1afef9d1968e_input.csv",
    "created_at": "2026-03-18T20:35:03.936559Z",
    "updated_at": "2026-03-18T20:35:16.658894Z",
    "total_category_mappings": 4,
    "total_attribute_mappings": 0,
    "workflow_id": "2345943b-91dd-4a3b-a923-b5c524049dcc",
    "workflow_status": "COMPLETED",
    "tenant_id": "268465dd-71f5-4179-959c-9bac01029451",
    "workflow_phase": "PRE_PROCESS",
    "domain": "acme.com",
    "total_items": 0,
    "processed_items": 0,
    "successful_items": 0,
    "failed_items": 0,
    "total_chunks": 0,
    "processed_chunks": 0,
    "input_file_id": "69bb0c78826cb2bb154da262",
    "output_file_id": null,
    "error_file_id": null,
    "review_required": false,
    "review_task_id": null,
    "enrichment_workflow_id": null,
    "error_message": null
}

Wait for the status to be set to COMPLETED. Once processing is complete, your products will appear in Activate. Based on your category structure, products will be organized accordingly—for example, sweaters under Tops > Sweaters and t-shirts under Tops > T-Shirts.

Activate

API Endpoints

​Prerequisites

​Step 1: Postman Environment Setup

​Create a new environment

​Add the environment variables

​Step 2: Authentication

​Create and set the access token

​Step 3 (Optional): Import Attribute Definitions

​Expected CSV columns for each attribute definition

​Request

​Check the import status

​Step 4: Import Your Products

​Expected CSV columns

​Request

​Check the import status

Prerequisites

Step 1: Postman Environment Setup

Create a new environment

Add the environment variables

Step 2: Authentication

Create and set the access token

Step 3 (Optional): Import Attribute Definitions

Expected CSV columns for each attribute definition

Request

Check the import status

Step 4: Import Your Products

Expected CSV columns

Request

Check the import status