Property Groups

Property groups define the attributes used to create product variants. For example, a "T-Shirt" property group might contain a Color property (Red, Blue, Green) and a Size property (S, M, L, XL).

Structure

Property groups have a three-level hierarchy:

PropertyGroup: A named collection of properties, scoped to a company
Property: An attribute dimension (Color, Size, Material, etc.)
PropertyValue: A specific option within a property, with a machine-readable code and a human-readable value

Creating a property group

Use propertyGroupCreate to create a group with its properties and values in a single call:

mutation {
  propertyGroupCreate(
    companyId: 1
    data: {
      name: "T-Shirt Options"
      visible: 1
      properties: [
        {
          name: "Color"
          ordering: 1
          visible: 1
          values: [
            { code: "RED", value: "Red", ordering: 1, visible: 1 }
            { code: "BLUE", value: "Blue", ordering: 2, visible: 1 }
            { code: "GREEN", value: "Green", ordering: 3, visible: 1 }
          ]
        },
        {
          name: "Size"
          ordering: 2
          visible: 1
          values: [
            { code: "S", value: "Small", ordering: 1, visible: 1 }
            { code: "M", value: "Medium", ordering: 2, visible: 1 }
            { code: "L", value: "Large", ordering: 3, visible: 1 }
          ]
        }
      ]
    }
  ) {
    errors { field msg }
    data {
      propertyGroupId
      name
      properties {
        propertyId
        name
        ordering
        values {
          propertyValueId
          code
          value
          ordering
        }
      }
    }
  }
}

The response includes the generated UUIDs (propertyGroupId, propertyId, propertyValueId) that you'll need when creating variants.

Field reference

PropertyGroupInsert:

Field	Type	Description
`name`	`String!`	Group name (unique per company)
`visible`	`Int!`	`1` = visible, `0` = hidden
`properties`	`[PropertyInsert!]!`	At least one property required

PropertyInsert:

Field	Type	Description
`name`	`String!`	Property name (e.g. "Color")
`ordering`	`Int!`	Display order (starting from 1)
`visible`	`Int!`	`1` = visible, `0` = hidden
`values`	`[PropertyValueInsert!]!`	The available options

PropertyValueInsert:

Field	Type	Description
`code`	`String!`	Machine-readable code (e.g. "RED"). Unique within the property. Used to auto-generate variant references.
`value`	`String!`	Human-readable label (e.g. "Red")
`ordering`	`Int!`	Display order
`visible`	`Int!`	`1` = visible, `0` = hidden

Codes matter for variant references

When you create product variants, the API auto-generates each variant's reference by combining the parent product's reference with the property value codes. For example, a parent with reference "TSHIRT" and values Color=RED, Size=S produces the variant reference "TSHIRT-RED-S".

Keep codes short and meaningful. The parent reference is limited to 30 characters when the product has variants, and the full variant reference (parent + codes + separators) must fit within 50 characters total. Property value codes themselves can be up to 30 characters, but in practice you should keep them concise to stay within the combined limit.

Querying property groups

List all groups

query {
  propertyGroups(companyId: 1, options: {
    pagination: { page: 1, qty: 20 }
  }) {
    data {
      propertyGroupId
      name
      properties {
        propertyId
        name
        values {
          propertyValueId
          code
          value
        }
      }
    }
    options {
      pagination {
        page
        qty
        count
      }
    }
  }
}

Get a single group

query {
  propertyGroup(companyId: 1, propertyGroupId: "uuid-here") {
    data {
      propertyGroupId
      name
      properties {
        propertyId
        name
        ordering
        values {
          propertyValueId
          code
          value
          ordering
          deletable
        }
        deletable
      }
      deletable
    }
  }
}

The deletable field on each level tells you whether that item can be safely deleted without affecting existing products.

Updating a property group

Use propertyGroupUpdate to modify a group. You can rename the group, add/remove/update properties, and add/remove/update values, all in a single call.

Adding a new value to an existing property

To add a value, include the existing properties and values with their IDs, plus the new value without an ID:

mutation {
  propertyGroupUpdate(
    companyId: 1
    data: {
      propertyGroupId: "group-uuid"
      properties: [
        {
          propertyId: "color-uuid"
          values: [
            { propertyValueId: "red-uuid", code: "RED", value: "Red", ordering: 1, visible: 1 }
            { propertyValueId: "blue-uuid", code: "BLUE", value: "Blue", ordering: 2, visible: 1 }
            { propertyValueId: "green-uuid", code: "GREEN", value: "Green", ordering: 3, visible: 1 }
            { code: "YELLOW", value: "Yellow", ordering: 4, visible: 1 }
          ]
        }
      ]
    }
  ) {
    errors { field msg }
    data {
      propertyGroupId
      properties {
        propertyId
        name
        values {
          propertyValueId
          code
          value
        }
      }
    }
  }
}

The logic is:

Entries with an ID are updated
Entries without an ID are created
Existing entries not included are deleted

Replacement semantics

When you send a properties or values array in an update, you must include all entries you want to keep. Any existing entry omitted from the array will be deleted.

Adding a new property

Similarly, include a new property without a propertyId:

properties: [
  { propertyId: "color-uuid", name: "Color", ordering: 1, visible: 1, values: [...] },
  { propertyId: "size-uuid", name: "Size", ordering: 2, visible: 1, values: [...] },
  { name: "Material", ordering: 3, visible: 1, values: [
    { code: "COTTON", value: "Cotton", ordering: 1, visible: 1 },
    { code: "POLY", value: "Polyester", ordering: 2, visible: 1 }
  ]}
]

Deletion constraints

Property groups, properties, and values are protected by referential integrity:

Level	Can delete when...
PropertyGroup	No products reference this group (`propertyGroupId`)
Property	No product variants use values from this property
PropertyValue	No product variants use this specific value

Check the deletable field on each item to know if deletion is safe. Attempting to delete a referenced item returns an error.

mutation {
  propertyGroupDelete(companyId: 1, propertyGroupId: ["group-uuid"]) {
    errors
    deletedCount
  }
}

Next steps

Variants: Use property groups to create product variants
See PropertyGroupInsert and PropertyGroupRead for all fields