Products API: Catalog and PIM Management

The Products API gives you full control over your Product Information Management (PIM) catalog. Use it to build out your product hierarchy — from top-level products and their variants to the brands, categories, attributes, and media assets that describe them. Every request is scoped to your tenant and organization, so data is always isolated to your account.

All requests require three headers: Authorization: Bearer YOUR_TOKEN, X-Tenant-ID: YOUR_TENANT_ID, and X-Org-ID: YOUR_ORG_ID.

List products

Retrieve all products for your tenant. The response returns up to 100 products ordered by creation date. GET /api/v1/pim/products

Headers

string

required

Bearer token from your authentication provider.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Response

array

Array of product objects.

Show Product fields

string

UUID of the product.

string

Organization the product belongs to.

string

Tenant the product belongs to.

string

Product display name.

string

Product description.

string

Category slug or name.

string

Product status, e.g. ACTIVE or DRAFT.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

curl https://api.synq.app/api/v1/pim/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Classic Wool Sweater",
    "description": "100% merino wool, machine washable.",
    "category": "apparel",
    "status": "ACTIVE",
    "created_at": "2024-06-01T10:00:00Z",
    "updated_at": "2024-06-15T08:30:00Z"
  }
]

Create a product

Create a new product in your catalog. The new product is assigned ACTIVE status by default. POST /api/v1/pim/products

Headers

string

required

Bearer token from your authentication provider.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Body

string

required

Display name of the product.

string

Long-form product description.

string

Category slug to associate with the product.

Response

Returns the newly created product object.

curl -X POST https://api.synq.app/api/v1/pim/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Wool Sweater",
    "description": "100% merino wool, machine washable.",
    "category": "apparel"
  }'

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Classic Wool Sweater",
  "description": "100% merino wool, machine washable.",
  "category": "apparel",
  "status": "ACTIVE",
  "created_at": "2024-06-01T10:00:00Z",
  "updated_at": "2024-06-01T10:00:00Z"
}

Get a product

Retrieve a single product by its ID. GET /api/v1/pim/products/{id}

Path parameters

string

required

UUID of the product to retrieve.

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Classic Wool Sweater",
  "description": "100% merino wool, machine washable.",
  "category": "apparel",
  "status": "ACTIVE",
  "created_at": "2024-06-01T10:00:00Z",
  "updated_at": "2024-06-15T08:30:00Z"
}

Update a product

Update the title, description, or category of an existing product. PUT /api/v1/pim/products/{id}

Path parameters

string

required

UUID of the product to update.

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Body

string

New display name.

string

Updated product description.

string

Updated category slug.

curl -X PUT https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"title": "Premium Wool Sweater"}'

Delete a product

Permanently delete a product from your catalog. Returns 204 No Content on success. DELETE /api/v1/pim/products/{id}

Path parameters

string

required

UUID of the product to delete.

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl -X DELETE https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

Create a variant

Add a variant (e.g. size, color combination) to an existing product. POST /api/v1/pim/products/{product_id}/variants

Path parameters

string

required

UUID of the parent product.

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Body

string

Stock-keeping unit identifier for this variant.

string

Barcode (e.g. UPC or EAN) for this variant.

number

Unit price of the variant.

string

ISO 4217 currency code, e.g. USD.

curl -X POST https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901/variants \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "WOOL-SWTR-M-BLU",
    "price": 89.99,
    "currency": "USD"
  }'

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "product_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sku": "WOOL-SWTR-M-BLU",
  "price": "89.99",
  "currency": "USD",
  "created_at": "2024-06-01T10:05:00Z"
}

Get dashboard stats

Return aggregate counts for your PIM catalog — total products, variants, brands, categories, and more. GET /api/v1/pim/stats

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl https://api.synq.app/api/v1/pim/stats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

{
  "total_products": 142,
  "active_products": 138,
  "total_variants": 610,
  "total_brands": 12,
  "total_categories": 8,
  "validation_issues": 3
}

Export products

Queue an asynchronous export of your full product catalog. Returns 202 Accepted immediately. You will be notified when the export file is ready for download. POST /api/v1/pim/export

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl -X POST https://api.synq.app/api/v1/pim/export \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

{
  "status": "success",
  "message": "Export job queued. You will be notified when the file is ready in Cloud Storage."
}

Bulk jobs

Run or monitor large-scale catalog operations such as bulk price updates or mass status changes. GET /api/v1/pim/bulk-jobs — list bulk jobs POST /api/v1/pim/bulk-jobs — create a bulk job

Query parameters (GET)

string

Filter by job type. Defaults to BULK_UPDATE.

Body (POST)

string

required

Type of bulk operation, e.g. BULK_UPDATE or BULK_DELETE.

object

JSON payload passed to the job processor.

curl -X POST https://api.synq.app/api/v1/pim/bulk-jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "BULK_UPDATE",
    "payload": { "status": "ACTIVE" }
  }'

{
  "id": "d4e5f6a7-b8c9-0123-defa-456789012345",
  "job_type": "BULK_UPDATE",
  "status": "PENDING",
  "created_at": "2024-06-01T11:00:00Z"
}

Validation issues

Retrieve a list of catalog validation problems, such as products missing required attributes or invalid SKUs. GET /api/v1/pim/validation

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl https://api.synq.app/api/v1/pim/validation \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

PIM audit events

Retrieve all PIM-specific audit events for your tenant, such as product creation, updates, and deletions. GET /api/v1/pim/audit

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

curl https://api.synq.app/api/v1/pim/audit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

[
  {
    "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "action": "PRODUCT_CREATED",
    "entity_type": "PRODUCT",
    "entity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "actor_email": "alice@example.com",
    "ip_address": "203.0.113.42",
    "details": { "title": "Classic Wool Sweater" },
    "created_at": "2024-06-01T10:00:00Z"
  }
]

Brands

Associate products with brand identities. GET /api/v1/pim/brands — list brands POST /api/v1/pim/brands — create a brand

Body (POST)

string

required

Brand display name.

string

Brand description.

string

URL to the brand logo image.

curl -X POST https://api.synq.app/api/v1/pim/brands \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nordvik",
    "description": "Scandinavian outdoor apparel.",
    "logoUrl": "https://cdn.example.com/nordvik-logo.png"
  }'

Attributes, attribute groups, and templates

Define reusable product attributes and organize them into groups or product type templates.

Method	Endpoint	Description
`GET`	`/api/v1/pim/attributes`	List attributes
`POST`	`/api/v1/pim/attributes`	Create attribute
`GET`	`/api/v1/pim/attribute-groups`	List attribute groups
`POST`	`/api/v1/pim/attribute-groups`	Create attribute group
`GET`	`/api/v1/pim/templates`	List product templates
`POST`	`/api/v1/pim/templates`	Create product template

Body for `POST /api/v1/pim/attributes`

string

required

Attribute display name, e.g. Color.

string

required

URL-safe key, e.g. color.

string

Data type: TEXT, NUMBER, BOOLEAN, or SELECT. Defaults to TEXT.

curl -X POST https://api.synq.app/api/v1/pim/attributes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Color", "slug": "color", "type": "TEXT"}'

Media

Attach images and other media assets to products or their variants. GET /api/v1/pim/media — list media (supports ?product_id= and ?variant_id= query filters) POST /api/v1/pim/media — attach a media asset

Body (POST)

string

required

Publicly accessible URL of the media asset.

string

UUID of the product to attach media to.

string

UUID of the variant to attach media to.

string

Accessible description of the image.

integer

Display order (lower numbers appear first).

curl -X POST https://api.synq.app/api/v1/pim/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "url": "https://cdn.example.com/wool-sweater-front.jpg",
    "alt_text": "Classic Wool Sweater — front view",
    "sort_order": 1
  }'

​List products

​Headers

​Response

​Create a product

​Headers

​Body

​Response

​Get a product

​Path parameters

​Headers

​Update a product

​Path parameters

​Headers

​Body

​Delete a product

​Path parameters

​Headers

​Create a variant

​Path parameters

​Headers

​Body

​Get dashboard stats

​Headers

​Export products

​Headers

​Bulk jobs

​Query parameters (GET)

​Body (POST)

​Validation issues

​Headers

​PIM audit events

​Headers

​Categories

​Body (POST)

​Brands

​Body (POST)

​Attributes, attribute groups, and templates

​Body for POST /api/v1/pim/attributes

​Media

​Body (POST)

List products

Headers

Response

Create a product

Headers

Body

Response

Get a product

Path parameters

Headers

Update a product

Path parameters

Headers

Body

Delete a product

Path parameters

Headers

Create a variant

Path parameters

Headers

Body

Get dashboard stats

Headers

Export products

Headers

Bulk jobs

Query parameters (GET)

Body (POST)

Validation issues

Headers

PIM audit events

Headers

Categories

Body (POST)

Brands

Body (POST)

Attributes, attribute groups, and templates

Body for `POST /api/v1/pim/attributes`

Media

Body (POST)