Skip to main content
Attributes are the building blocks of structured product metadata in Synq. An attribute defines a named, typed property — such as Material (type TEXT) or Weight (type NUMBER) — that can be attached to products and variants. You group related attributes into attribute groups to keep your data model organized (for example, putting Material, Care Instructions, and Country of Origin into a Fabric Details group). Finally, you bundle attribute groups into product templates (also called product types), which act as reusable schemas: apply the “Apparel” template to all clothing products to ensure they always carry the same set of defined attributes. Media — product and variant images — is also managed through the PIM API and is covered at the end of this guide.
All requests require the standard headers: Authorization: Bearer <token>, X-Tenant-ID, and X-Org-ID.

​
Attributes

​
List attributes

Retrieve all active attributes for your tenant, ordered alphabetically by name. 
GET /api/v1/pim/attributes

curl https://api.synq.com/api/v1/pim/attributes \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
Response 200 OK 
[
  {
    "id": "a0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "Material",
    "slug": "material",
    "type": "TEXT",
    "created_at": "2024-10-01T09:00:00Z",
    "updated_at": "2024-10-01T09:00:00Z"
  },
  {
    "id": "a0b1c2d3-0002-4e5f-6a7b-8c9d0e1f2a3b",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "Weight (grams)",
    "slug": "weight-grams",
    "type": "NUMBER",
    "created_at": "2024-10-01T09:01:00Z",
    "updated_at": "2024-10-01T09:01:00Z"
  }
]

​
Create an attribute

POST /api/v1/pim/attributes
Request body
​
name
string
required
Human-readable label for the attribute (e.g., "Material").
​
slug
string
required
URL-safe unique identifier used to reference this attribute programmatically (e.g., "material").
​
type
string
The data type of attribute values. Defaults to TEXT if omitted. Common values: TEXT, NUMBER, BOOLEAN, DATE.
curl -X POST https://api.synq.com/api/v1/pim/attributes \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Material",
    "slug": "material",
    "type": "TEXT"
  }'
Response 200 OK 
{
  "id": "a0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "name": "Material",
  "slug": "material",
  "type": "TEXT",
  "created_at": "2024-11-15T13:00:00Z",
  "updated_at": "2024-11-15T13:00:00Z"
}
​
id
string
UUID for the new attribute. Use this when linking the attribute to an attribute group or product template.

​
Attribute groups

Attribute groups let you organize related attributes under a shared label. For example, a "Dimensions" group might contain Height, Width, Depth, and Weight.

​
List attribute groups

GET /api/v1/pim/attribute-groups

curl https://api.synq.com/api/v1/pim/attribute-groups \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
Response 200 OK 
[
  {
    "id": "g0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "Fabric Details",
    "description": "Textile composition and care information.",
    "created_at": "2024-10-01T09:00:00Z",
    "updated_at": "2024-10-01T09:00:00Z"
  }
]

​
Create an attribute group

POST /api/v1/pim/attribute-groups
Request body
​
name
string
required
Display name for the group (e.g., "Fabric Details").
​
description
string
An optional description of what this group covers.
curl -X POST https://api.synq.com/api/v1/pim/attribute-groups \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fabric Details",
    "description": "Textile composition and care information."
  }'
Response 200 OK 
{
  "id": "g0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "name": "Fabric Details",
  "description": "Textile composition and care information.",
  "created_at": "2024-11-15T13:10:00Z",
  "updated_at": "2024-11-15T13:10:00Z"
}

​
Product templates

A product template (called a product type in the API) is a named, reusable schema that bundles a set of attributes. When you assign a template to a product via product_type_id, your team knows exactly which attribute fields are expected to be filled in for that product type.

​
List templates

GET /api/v1/pim/templates

curl https://api.synq.com/api/v1/pim/templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
Response 200 OK 
[
  {
    "id": "t0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "Apparel",
    "description": "Standard template for all clothing products.",
    "created_at": "2024-10-01T09:00:00Z",
    "updated_at": "2024-10-01T09:00:00Z"
  }
]

​
Create a template

POST /api/v1/pim/templates
Request body
​
name
string
required
Display name for the template (e.g., "Apparel").
​
description
string
An optional description of the product category this template covers.
curl -X POST https://api.synq.com/api/v1/pim/templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Apparel",
    "description": "Standard template for all clothing products."
  }'
Response 200 OK 
{
  "id": "t0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "name": "Apparel",
  "description": "Standard template for all clothing products.",
  "created_at": "2024-11-15T13:20:00Z",
  "updated_at": "2024-11-15T13:20:00Z"
}
​
id
string
UUID for the template. Pass this as product_type_id when creating or updating a product to apply this template.

​
Media

Product and variant images are managed through the media endpoints. Each media record links a URL to either a product or a specific variant, with optional alt text and a sort order for controlling display sequence.

​
List media

Retrieve media records for your tenant. Pass product_id or variant_id as query parameters to filter results to a specific product or variant. 
GET /api/v1/pim/media

curl "https://api.synq.com/api/v1/pim/media?product_id=018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
Response 200 OK 
[
  {
    "id": "m0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "product_id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
    "variant_id": null,
    "url": "https://cdn.example.com/products/merino-sweater-hero.jpg",
    "alt_text": "Merino wool crew neck sweater in navy",
    "sort_order": 1,
    "created_at": "2024-11-15T13:30:00Z",
    "updated_at": "2024-11-15T13:30:00Z"
  }
]

​
Create media

POST /api/v1/pim/media
Request body
​
product_id
string
UUID of the product this image belongs to. Provide either product_id or variant_id.
​
variant_id
string
UUID of the variant this image belongs to. Provide either product_id or variant_id.
​
url
string
required
A fully qualified URL to the image file.
​
alt_text
string
Descriptive alt text for the image, used for accessibility and SEO.
​
sort_order
integer
Integer position controlling the display order of images. Lower numbers appear first.
curl -X POST https://api.synq.com/api/v1/pim/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
    "url": "https://cdn.example.com/products/merino-sweater-hero.jpg",
    "alt_text": "Merino wool crew neck sweater in navy",
    "sort_order": 1
  }'
Response 200 OK 
{
  "id": "m0b1c2d3-0001-4e5f-6a7b-8c9d0e1f2a3b",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "product_id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
  "variant_id": null,
  "url": "https://cdn.example.com/products/merino-sweater-hero.jpg",
  "alt_text": "Merino wool crew neck sweater in navy",
  "sort_order": 1,
  "created_at": "2024-11-15T13:30:00Z",
  "updated_at": "2024-11-15T13:30:00Z"
}

​
Putting it together

Here is the recommended sequence for setting up a fully attributed product type:
1

Create your attributes

Define each attribute your product type needs. For an “Apparel” template you might create Material (TEXT), Care Instructions (TEXT), and Weight (NUMBER).
2

Create an attribute group

Group related attributes under a meaningful label, such as "Fabric Details".
3

Create the product template

Create a POST /api/v1/pim/templates record named "Apparel".
4

Link attributes to the template

Associate each attribute with the template by providing the template’s UUID as product_type_id when creating products. When you create a product and set product_type_id to this template’s UUID, it signals which attributes should be populated for that product.
5

Apply the template to products

When creating or updating products, set product_type_id to the template’s UUID. This connects the product to the expected attribute schema.