ProductFamily

A merchant catalog item — a group of related products (variants).

Emits: PRODUCT_FAMILY_CREATED, PRODUCT_FAMILY_UPDATED, PRODUCT_FAMILY_DELETED

Required scopes: products_read, products_write

attribute · Attribute

Look up a single attribute on this family by its name, if set.

Requires: products_read

Show fields

Arguments

name · String! · required

The machine name of the attribute to look up.

Fields

description · String

An optional description of what the attribute represents.

displayName · String! · required

The human-readable label shown for the attribute.

id · ID! · required

The unique identifier of the attribute’s definition.

name · String! · required

The attribute’s machine name, unique within the account.

type · AttributeType! · required

The data type of the attribute’s value.

value · JSON

The attribute’s value, resolved to the typed JSON form for its type — read type to know the shape. E.g. SHORT_TEXT → a string, WEIGHT → { value, unit }, MONEY → { amount, currency }. Null if unset. See AttributeType for each type’s shape.

attributes · [Attribute!]! · required

The merchant-defined attributes set on this family.

Show fields

description · String

An optional description of what the attribute represents.

displayName · String! · required

The human-readable label shown for the attribute.

id · ID! · required

The unique identifier of the attribute’s definition.

name · String! · required

The attribute’s machine name, unique within the account.

type · AttributeType! · required

The data type of the attribute’s value.

value · JSON

The attribute’s value, resolved to the typed JSON form for its type — read type to know the shape. E.g. SHORT_TEXT → a string, WEIGHT → { value, unit }, MONEY → { amount, currency }. Null if unset. See AttributeType for each type’s shape.

createdAt · DateTime! · required

When the record was created.

description · String! · required

The product family’s long-form description.

id · ID! · required

The id of this product family.

image · ProductFamilyImage

The first (default) image for this family, if any.

Requires: products_read

Show fields

altText · String! · required

Alternative text describing the image.

default · Boolean! · required

Whether this is the default image.

id · ID! · required

The id of this image.

position · Int! · required

The image’s ordering position.

url · String! · required

The public URL of the image.

images · ProductFamilyImageConnection! · required

A paginated list of the family’s images.

Requires: products_read

Show fields

Arguments

after · String

Forward pagination cursor — returns items after it. Pass an edges[].cursor or pageInfo.endCursor from a previous page.

before · String

Backward pagination cursor — returns items before it. Pass an edges[].cursor or pageInfo.startCursor from a previous page.

first · Int

Forward pagination: returns the first N items (max 100, default 25). Use with after; mutually exclusive with last/before.

last · Int

Backward pagination: returns the last N items (max 100, default 25). Use with before; mutually exclusive with first/after.

Fields

edges · [ProductFamilyImageEdge!]! · required

The list of edges (each a node plus its pagination cursor).

Show fields

cursor · String! · required

Opaque cursor for this item; pass to after/before to page from here.

node · ProductFamilyImage! · required

The item at this edge.

nodes · [ProductFamilyImage!]! · required

The nodes in this page, without the edge/cursor wrapper — a convenience over edges.

Show fields

altText · String! · required

Alternative text describing the image.

default · Boolean! · required

Whether this is the default image.

id · ID! · required

The id of this image.

position · Int! · required

The image’s ordering position.

url · String! · required

The public URL of the image.

pageInfo · PageInfo! · required

Pagination metadata for the current page.

Show fields

endCursor · String

Cursor of the last edge in this page; pass to after to page forward.

hasNextPage · Boolean! · required

Whether more items exist after this page (drives forward pagination with first/after).

hasPreviousPage · Boolean! · required

Whether more items exist before this page (drives backward pagination with last/before).

startCursor · String

Cursor of the first edge in this page; pass to before to page backward.

options · [ProductFamilyOption!]! · required

The variant options (e.g. Size, Color) for this family.

Show fields

id · ID! · required

The id of this option.

name · String! · required

The option’s name (e.g. Size).

position · Int! · required

The option’s ordering position within the family.

values · [String!]! · required

The allowed values for this option (e.g. S, M, L).

products · ProductConnection! · required

A paginated list of the products (variants) in this family.

Requires: products_read

Show fields

Arguments

after · String

Forward pagination cursor — returns items after it. Pass an edges[].cursor or pageInfo.endCursor from a previous page.

before · String

Backward pagination cursor — returns items before it. Pass an edges[].cursor or pageInfo.startCursor from a previous page.

first · Int

Forward pagination: returns the first N items (max 100, default 25). Use with after; mutually exclusive with last/before.

last · Int

Backward pagination: returns the last N items (max 100, default 25). Use with before; mutually exclusive with first/after.

Fields

edges · [ProductEdge!]! · required

The list of edges (each a node plus its pagination cursor).

Show fields

cursor · String! · required

Opaque cursor for this item; pass to after/before to page from here.

node · Product! · required

The item at this edge.

nodes · [Product!]! · required

The nodes in this page, without the edge/cursor wrapper — a convenience over edges.

Show fields

attribute · Attribute

Look up a single attribute on this product by its name, if set.

Requires: products_read

Show fields

Arguments

name · String! · required

The machine name of the attribute to look up.

attributes · [Attribute!]! · required

The merchant-defined attributes set on this product.

barcodes · [String!]! · required

Barcodes associated with this product.

cost · Money

The merchant’s unit cost for the product.

createdAt · DateTime! · required

When the record was created.

description · String! · required

The product’s long-form description.

dimensions · Dimensions

The product’s length, width, and height, expressed in a single shared unit.

hsCode · String

The Harmonized System code used for customs.

id · ID! · required

The id of this product.

image · ProductImage

The first (default) image for this product, if any.

Requires: products_read

images · ProductImageConnection! · required

A paginated list of the product’s images.

Requires: products_read

Show fields

Arguments

after · String

Forward pagination cursor — returns items after it. Pass an edges[].cursor or pageInfo.endCursor from a previous page.

before · String

Backward pagination cursor — returns items before it. Pass an edges[].cursor or pageInfo.startCursor from a previous page.

first · Int

Forward pagination: returns the first N items (max 100, default 25). Use with after; mutually exclusive with last/before.

last · Int

Backward pagination: returns the last N items (max 100, default 25). Use with before; mutually exclusive with first/after.

inventoryLevel · LocationInventoryLevel

This product’s inventory level at a single location, if any.

Requires: inventory_read

Show fields

Arguments

locationId · ID! · required

The id of the location to fetch the level at.

inventoryLevels · LocationInventoryLevelConnection! · required

Per-location inventory levels for this product.

Requires: inventory_read

Show fields

Arguments

after · String

Forward pagination cursor — returns items after it. Pass an edges[].cursor or pageInfo.endCursor from a previous page.

before · String

Backward pagination cursor — returns items before it. Pass an edges[].cursor or pageInfo.startCursor from a previous page.

first · Int

Forward pagination: returns the first N items (max 100, default 25). Use with after; mutually exclusive with last/before.

last · Int

Backward pagination: returns the last N items (max 100, default 25). Use with before; mutually exclusive with first/after.

options · [ProductOptionValue!]! · required

The variant’s selected option values (e.g. Size: M, Color: Red), ordered by the family’s option positions.

originCountry · String

The country of origin, as a country code.

physicalItem · Boolean! · required

Whether the product is a physical, shippable item.

price · Money

The product’s selling price.

productFamily · ProductFamily

The product family this product belongs to, if any.

Requires: products_read

sku · String

The stock keeping unit identifying this product.

tags · [String!]! · required

Free-form tags applied to the product.

taxCode · String

The tax code used to classify the product for taxation.

taxable · Boolean! · required

Whether the product is subject to tax.

title · String! · required

The product’s title.

upc · String

The Universal Product Code for this product.

updatedAt · DateTime! · required

When the record was last updated.

vendor · String

The vendor or manufacturer of the product.

weight · Weight

The product’s weight.

pageInfo · PageInfo! · required

Pagination metadata for the current page.

Show fields

endCursor · String

Cursor of the last edge in this page; pass to after to page forward.

hasNextPage · Boolean! · required

Whether more items exist after this page (drives forward pagination with first/after).

hasPreviousPage · Boolean! · required

Whether more items exist before this page (drives backward pagination with last/before).

startCursor · String

Cursor of the first edge in this page; pass to before to page backward.

tags · [String!]! · required

Free-form tags applied to the product family.

title · String! · required

The product family’s title.

updatedAt · DateTime! · required

When the record was last updated.

vendor · String

The vendor or manufacturer of the product family.