The product is the core resource in Synq’s Product Information Management (PIM) system. Every item you sell — whether a physical good, a digital download, or a bundle — lives as a product record scoped to your tenant. Each product carries a human-readable title, an optional description, a category label, and a lifecycle status (defaulting to ACTIVE). Products can have one or more variants (e.g., sizes and colors), belong to a structured category or brand, and carry rich custom attributes through product type templates.
Every request to the PIM API must include three headers:
Authorization: Bearer <token> — your API tokenX-Tenant-ID — the UUID of the tenant you are operating onX-Org-ID — the UUID of your organization
Requests that omit these headers receive a 401 Unauthorized response. List products
Retrieve up to 100 of your most recently updated products for a tenant.
Request
curl https://api.synq.com/api/v1/pim/products \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID"
200 OK
[
{
"id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
"title": "Merino Wool Crew Neck Sweater",
"category": "Knitwear",
"status": "ACTIVE",
"updated_at": "2024-11-15T10:32:00Z"
},
{
"id": "018e7c3a-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"title": "Classic Oxford Button-Down",
"category": "Shirts",
"status": "ACTIVE",
"updated_at": "2024-11-14T08:10:00Z"
}
]
The list endpoint returns a lightweight projection (id, title, category, status, updated_at). Fetch a single product by ID to retrieve the full record including SEO fields, flags, and metadata.
Create a product
Send a POST request with a JSON body to create a new product. The title field is required. The description and category fields are optional but recommended for catalog quality.
POST /api/v1/pim/products
The display name of the product shown to customers and operators.
A long-form description of the product.
A free-text category label. To use a structured category, associate the product with a category_id after creation.
curl -X POST https://api.synq.com/api/v1/pim/products \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"title": "Merino Wool Crew Neck Sweater",
"description": "Crafted from 100% Grade-A merino wool. Naturally temperature-regulating and machine washable.",
"category": "Knitwear"
}'
200 OK
{
"id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
"org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
"title": "Merino Wool Crew Neck Sweater",
"description": "Crafted from 100% Grade-A merino wool. Naturally temperature-regulating and machine washable.",
"status": "ACTIVE",
"category": "Knitwear",
"created_at": "2024-11-15T10:00:00Z",
"updated_at": "2024-11-15T10:00:00Z"
}
System-generated UUID for the new product. Use this to fetch, update, or delete the product later.
Defaults to ACTIVE on creation. Other lifecycle values include DRAFT and ARCHIVED.
Get a product by ID
Retrieve the full product record including all optional fields.
GET /api/v1/pim/products/{id}
curl https://api.synq.com/api/v1/pim/products/018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90 \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID"
200 OK
{
"id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
"org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
"title": "Merino Wool Crew Neck Sweater",
"description": "Crafted from 100% Grade-A merino wool.",
"short_description": "100% merino wool. Machine washable.",
"status": "ACTIVE",
"category": "Knitwear",
"brand": "NordicThread",
"is_taxable": true,
"is_returnable": true,
"seo_title": "Merino Wool Sweater – NordicThread",
"seo_description": "Shop our bestselling merino wool crew neck.",
"data_quality_score": 82,
"created_at": "2024-11-15T10:00:00Z",
"updated_at": "2024-11-15T10:00:00Z"
}
If the product ID does not exist within your tenant’s scope, the API returns 404 Not Found. Products soft-deleted via DELETE are also excluded from GET responses.
Update a product
Partially update a product’s title, description, or category. Only fields you include in the request body are changed — omitted fields retain their current values.
PUT /api/v1/pim/products/{id}
curl -X PUT https://api.synq.com/api/v1/pim/products/018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90 \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"title": "Merino Wool Crew Neck Sweater – 2025 Edition",
"description": "Updated for 2025 with a relaxed fit and reinforced cuffs.",
"category": "Knitwear"
}'
GET /products/{id} response.
Delete a product
Soft-delete a product. The record is retained with a timestamp and is excluded from all list and get operations.
DELETE /api/v1/pim/products/{id}
curl -X DELETE https://api.synq.com/api/v1/pim/products/018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90 \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID"
204 No Content
A successful deletion returns an empty body with status 204. If the product is not found or already deleted, the API returns 500 — verify the ID and tenant headers are correct.
Dashboard stats
Retrieve a real-time snapshot of your catalog’s health, including total product count, low-stock variants, out-of-stock variants, and total inventory value.
curl https://api.synq.com/api/v1/pim/stats \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-ID: $TENANT_ID" \
-H "X-Org-ID: $ORG_ID"
200 OK
{
"totalProducts": 1240,
"lowStockVariants": 37,
"outOfStockVariants": 12,
"totalInventoryValue": 482500.00
}
Count of active (non-deleted) products in the tenant.
Number of variants with fewer than 20 units available.
Number of variants with zero available units.
Sum of available quantity multiplied by cost price across all variants.