Variants

Inherit everything, override what differs

Variants inherit all attribute values from their parent record and store only the overrides. Build multi-level hierarchies — size, color, material — and use the resolved endpoint to merge the full ancestor chain into a single response.

Inheritance Model

A variant stores only overridden values. Every attribute not explicitly set is inherited from the parent entity or parent variant up the chain.

Multi-Level Hierarchy

Set parentId to the entity ID for level-1 variants, or to another variant ID for deeper levels (e.g., Size → Color).

Resolved Endpoint

The /resolved endpoint merges the full ancestor chain and returns effectiveValues, overriddenAttributes, and inheritedAttributes.

Non-Inheritable Attributes

Attributes marked inheritable: false in the schema are excluded from inheritance and must be set directly on each variant.

Endpoints

Method	Endpoint	Description
GET	`/variants`	List all variants (flat, paginated)
GET	`/records/:id/variants`	List variants for a record
POST	`/records/:id/variants`	Create a variant
GET	`/records/:id/variants/:vid`	Get a specific variant
PUT	`/records/:id/variants/:vid`	Update a variant
DELETE	`/records/:id/variants/:vid`	Delete a variant
GET	`/records/:id/variants/:vid/resolved`	Resolved variant with inherited values
PATCH	`/records/:id/variants/:vid/values/:attr`	Update single attribute on variant

List All Variants

Returns a flat, paginated list of all variants across all records. Useful for bulk operations and data exports.

Parameter	Type	Description
`schemaId`	string	Filter variants by parent record schema
`offset`	number	Pagination offset (default: 0)
`limit`	number	Page size (default: 50)

curl https://api.sigma-pim.com/api/v1/variants?schemaId=schema-apparel&limit=10 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "items": [
    {
      "id": "var-cw-s",
      "entityId": "ent-coastal-wb",
      "parentId": "ent-coastal-wb",
      "level": 1,
      "values": {
        "sku": [{ "scope": {}, "value": "CW-001-S" }],
        "weight": [{ "scope": {}, "value": 320 }]
      }
    }
  ],
  "total": 24,
  "offset": 0,
  "limit": 10
}

List Variants for a Record

Returns all variants belonging to a specific record. Optionally filter by hierarchy level or parent variant.

Parameter	Type	Description
`level`	number	Filter by variant level (1 = direct children)
`parentId`	string	Filter by parent variant ID

curl https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants?level=1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — size variants for the Coastal Windbreaker
[
  {
    "id": "var-cw-s",
    "entityId": "ent-coastal-wb",
    "parentId": "ent-coastal-wb",
    "level": 1,
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-S" }],
      "weight": [{ "scope": {}, "value": 320 }]
    }
  },
  {
    "id": "var-cw-m",
    "entityId": "ent-coastal-wb",
    "parentId": "ent-coastal-wb",
    "level": 1,
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-M" }],
      "weight": [{ "scope": {}, "value": 340 }]
    }
  },
  {
    "id": "var-cw-l",
    "entityId": "ent-coastal-wb",
    "parentId": "ent-coastal-wb",
    "level": 1,
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-L" }],
      "weight": [{ "scope": {}, "value": 360 }]
    }
  },
  {
    "id": "var-cw-xl",
    "entityId": "ent-coastal-wb",
    "parentId": "ent-coastal-wb",
    "level": 1,
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-XL" }],
      "weight": [{ "scope": {}, "value": 380 }]
    }
  }
]

Create Variant

Create a new variant under a record. Only include values that differ from the parent — everything else is inherited automatically. Set parentId to the entity ID for level-1 variants, or to another variant ID for deeper nesting.

Field	Type	Required	Description
`values`	`Record<string, ScopedValue[]>`	Yes	Attribute overrides (only what differs from parent)
`parentId`	string	No	Defaults to entity ID. Set to a variant ID for nested hierarchies

curl -X POST https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-S" }],
      "weight": [{ "scope": {}, "value": 320 }],
      "size-label": [{ "scope": {}, "value": "Small" }]
    }
  }'

// Response — 201 Created
{
  "id": "var-cw-s",
  "entityId": "ent-coastal-wb",
  "parentId": "ent-coastal-wb",
  "level": 1,
  "values": {
    "sku": [{ "scope": {}, "value": "CW-001-S" }],
    "weight": [{ "scope": {}, "value": 320 }],
    "size-label": [{ "scope": {}, "value": "Small" }]
  }
}

Get Variant

Retrieve a specific variant by ID. Returns only the stored overrides, not inherited values. Use the /resolved endpoint to see the full merged result.

curl https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants/var-cw-s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Update Variant

Replace the variant's overridden values. To remove an override and revert to the inherited value, omit the attribute from the update body.

curl -X PUT https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants/var-cw-s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "sku": [{ "scope": {}, "value": "CW-001-S" }],
      "weight": [{ "scope": {}, "value": 315 }],
      "size-label": [{ "scope": {}, "value": "Small" }]
    }
  }'

Delete Variant

Permanently remove a variant. Returns 204 No Content on success.

curl -X DELETE https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants/var-cw-s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Resolved Variant

Merges the full ancestor chain (parent entity → parent variant → child variant) and returns the complete set of effective values. The response clearly indicates which attributes were inherited and which were overridden.

curl https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants/var-cw-s/resolved \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — ResolvedVariant
{
  "id": "var-cw-s",
  "entityId": "ent-coastal-wb",
  "parentId": "ent-coastal-wb",
  "level": 1,
  "effectiveValues": {
    "product-name": [
      { "scope": {}, "value": "Coastal Windbreaker" },
      { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" }
    ],
    "description": [
      { "scope": {}, "value": "Lightweight water-resistant jacket for coastal adventures" }
    ],
    "price": [{ "scope": {}, "value": 129.99 }],
    "sku": [{ "scope": {}, "value": "CW-001-S" }],
    "weight": [{ "scope": {}, "value": 320 }],
    "size-label": [{ "scope": {}, "value": "Small" }]
  },
  "overriddenAttributes": ["sku", "weight", "size-label"],
  "inheritedAttributes": ["product-name", "description", "price"]
}

Update Single Attribute

Update a single attribute on a variant without touching other values. This is useful for targeted edits, especially when working with scoped values across dimensions.

curl -X PATCH https://api.sigma-pim.com/api/v1/records/ent-coastal-wb/variants/var-cw-s/values/weight \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopedValues": [
      { "scope": {}, "value": 318 }
    ]
  }'

// Response — updated variant
{
  "id": "var-cw-s",
  "entityId": "ent-coastal-wb",
  "parentId": "ent-coastal-wb",
  "level": 1,
  "values": {
    "sku": [{ "scope": {}, "value": "CW-001-S" }],
    "weight": [{ "scope": {}, "value": 318 }],
    "size-label": [{ "scope": {}, "value": "Small" }]
  }
}

Previous Records Next Catalogs