Single Product

About

The product query retrieves a single product by its unique identifier, SKU, or URL key. Use this query to:

• Fetch individual products for detail pages
• Look up products by different identifier types (ID, SKU, URL)
• Display complete product information including images, variants, and attributes
• Show product pricing, descriptions, and SEO metadata
• Retrieve inventory and availability status
• Build product-specific API integrations
• Generate product detail pages with all metadata

This query supports multiple lookup methods (ID, SKU, or URL key) and can return minimal data for previews or comprehensive data for full product detail pages, making it flexible for various use cases.

Why Booking Product Types Are Documented Separately

All product types (simple, configurable, grouped, bundle, downloadable, virtual) share the same core fields (name, sku, price, images, variants, attributeValues, etc.) and can be queried using the same base query structure. However, booking products are documented with separate examples because each booking type (Appointment, Rental, Default, Table, Event) exposes its own unique relationship and slot structure through the bookingProducts field. These sub-types have different fields and response shapes (e.g., appointmentSlot, rentalSlot, defaultSlot, tableSlot, eventTickets), so dedicated examples are provided to show how to query each one correctly.

Arguments

Argument	Type	Description
id	ID	Product's unique system identifier. Use this for direct lookups.
sku	String	Stock Keeping Unit. Alternative identifier for product lookup.
urlKey	String	URL-friendly product slug. Alternative lookup method.
include_variants	Boolean	Include product variants (colors, sizes, options). Default: false
include_images	Boolean	Include product images. Default: false
include_attributes	Boolean	Include custom product attributes. Default: true
image_resolution	String	Image quality: thumbnail, medium, large, original. Default: large
include_recommendations	Boolean	Include related and recommended products. Default: false

Possible Returns

Field	Type	Description
id	ID!	Unique product identifier.
name	String!	Product display name.
sku	String!	Stock Keeping Unit for inventory tracking.
urlKey	String!	URL-friendly product slug for SEO.
type	String!	Product type (simple, configurable, grouped, bundle).
description	String	Full product description with formatting.
shortDescription	String	Brief product summary.
price	Float!	Base product price.
specialPrice	Float	Promotional/discounted price if applicable.
superAttributeOptions	String (JSON)	JSON-encoded array of configurable attribute options (e.g. color, size) with their available values. Only populated for configurable products — returns the attributes and selectable options that define the product's variants.
combinations	String (JSON)	JSON-encoded object mapping variant product IDs to their attribute option combinations. Each key is a variant ID and the value contains the attribute option IDs that define that variant. Only populated for configurable products.
taxClass	String	Tax classification for the product.
images	[ProductImage!]	Array of product images with URLs and metadata.
images.url	String!	Image URL.
images.altText	String	Image alt text for accessibility.
images.position	Int	Image order in gallery.
images.width	Int	Image width in pixels.
images.height	Int	Image height in pixels.
attributes	[ProductAttribute!]	Custom product attributes and values.
variants	[ProductVariant!]	Product variants (colors, sizes, options).
variants.sku	String!	Variant SKU.
variants.price	Float!	Variant-specific price.
inventory	InventoryInfo!	Stock availability information.
inventory.stock	Int!	Current stock quantity.
inventory.status	String!	Stock status (in_stock, out_of_stock, low_stock).
categories	[Category!]!	Categories this product belongs to.
tags	[String!]	Product tags and labels.
seo	ProductSEO!	SEO metadata.
status	String!	Product status (active, draft, inactive).
visibility	String!	Visibility status (visible, not visible, search only).
createdAt	DateTime!	Product creation date.
updatedAt	DateTime!	Last modification date.

Configurable Products

A configurable product is a product that has multiple variants based on attributes like color, size, or material. For example, a T-shirt that comes in 3 colors and 2 sizes would have 6 variants. When querying a configurable product, two additional fields are returned that are essential for building a variant selection UI:

superAttributeOptions

This field returns a JSON-encoded string containing the configurable attributes and their selectable options. Each entry includes:

• code — the attribute code (e.g. color, size)
• label — the display label (e.g. Color, Size)
• options — an array of available values, each with an id and label

Use this field to render attribute dropdowns (e.g. color picker, size selector) on the product detail page.

combinations

This field returns a JSON-encoded object that maps each variant product ID to its specific attribute option combination. For example:

{"8": {"color": 3, "size": 7}, "9": {"color": 3, "size": 8}}

This means variant ID 8 is the product with color option 3 and size option 7. When a customer selects a color and size from the dropdowns, use this mapping to resolve which variant ID to load (for pricing, stock, images, etc.).

How they work together

1. Use superAttributeOptions to render the attribute dropdowns on your product page
2. When the customer selects options (e.g. Color: Blue, Size: M), match their selection against the combinations object to find the corresponding variant ID
3. Use that variant ID to display the correct price, stock status, and images for the selected variant

For non-configurable product types (simple, grouped, bundle, etc.), both superAttributeOptions and combinations will be null.

Downloadable Products

A downloadable product contains digital files that customers can download after purchase. Each downloadable product can have two types of sample files:

downloadableLinks

These are the individual download links that make up the product (e.g. Track 1, Track 2 for a music album, or Chapter 1, Chapter 2 for an e-book). Each link has its own price and can optionally have a sample file attached for preview. The fields sampleFile, sampleFileUrl, and sampleUrl provide details about the sample associated with each link.

downloadableSamples

These are product-level samples — general preview files for the entire product rather than a specific link. The _id from each sample node is used to download the sample via:

GET /api/shop/downloadable/download-sample/sample/{_id}

Downloading purchased files

After a customer purchases a downloadable product, the purchased files can be downloaded using the _id from the Get Downloadable Products query (not the product query). See the Download Downloadable Product page for full details.

Sample downloads are free and do not require authentication. Purchased file downloads require customer authentication and have a limited number of downloads.

Grouped Products

A grouped product bundles multiple simple products together, allowing customers to purchase them as a set. Unlike a bundle product where the customer selects options, a grouped product presents each child product with a default quantity that the customer can adjust before adding to cart.

groupedProducts

This field returns the list of associated child products via the groupedProducts connection. Each node contains:

• id — the grouped product relationship ID
• qty — the default quantity for that child product in the group
• sortOrder — the display order of the child product
• associatedProduct — the full child product details including id, name, sku, price, formattedPrice, specialPrice, formattedSpecialPrice, and images

Pricing behavior

A grouped product's own price is always 0 because it does not have a standalone price. Instead, the price range is derived from its child products:

• minimumPrice — the lowest priced child product
• maximumPrice — the highest priced child product

The customer's total depends on which child products they select and in what quantities.

For non-grouped product types, the groupedProducts field will return an empty edges array.

Booking Product Types

All standard product types (simple, configurable, grouped, bundle, downloadable, virtual) share the same core fields and can be queried using any of the general examples above. Booking products, however, require special attention because each booking type exposes a different relationship with its own unique fields through the bookingProducts connection.

The bookingProducts field returns a type that determines which slot/ticket relationship contains the data:

Booking Type	Relationship Field	Key Fields	Use Case
Appointment	appointmentSlot	duration, breakTime, sameSlotAllDays, slots	Salon visits, doctor appointments, consultations
Rental	rentalSlot	rentingType, dailyPrice, hourlyPrice, slots	Equipment rental, vehicle hire, venue booking
Default	defaultSlot	bookingType, duration, breakTime, slots	General time-slot bookings
Table	tableSlot	priceType, guestLimit, duration, breakTime, preventSchedulingBefore, slots	Restaurant reservations, meeting rooms
Event	eventTickets	price, qty, specialPrice, specialPriceFrom, specialPriceTo	Concerts, workshops, conferences

TIP

Only the relationship matching the product's booking type will contain data. For example, an appointment booking product will have data in appointmentSlot but not in rentalSlot or tableSlot. Always check the type field first to determine which relationship to query.

Product Fields Reference

Below is a complete reference of all available fields on the Product type. Use this as a lookup when building your queries — include only the fields you need.

Basic Information

Field	Type	Description
id	ID!	Unique product identifier in IRI format (e.g. /api/shop/products/1)
_id	Int!	Numeric database ID
sku	String!	Stock Keeping Unit — unique product code for inventory tracking
type	String!	Product type: simple, virtual, configurable, grouped, bundle, downloadable, booking
name	String	Product display name
urlKey	String	URL-friendly slug (e.g. premium-wireless-headphones)
status	String	Product status (1 = active, 0 = inactive)
locale	String	Locale of the returned product data
channel	String	Channel the product belongs to
productNumber	String	Optional product number assigned by the store
additional	Iterable	Additional product data stored as key-value pairs
createdAt	String	Product creation timestamp
updatedAt	String	Last modification timestamp

Descriptions

Field	Type	Description
description	String	Full product description (plain text)
descriptionHtml	String	Full product description with HTML formatting preserved
shortDescription	String	Brief product summary for listing pages

Pricing

Field	Type	Description
price	String	Base catalog price. Reflects active currency conversion.
specialPrice	String	Discounted price if set, otherwise null
specialPriceFrom	String	Start date for the special price (YYYY-MM-DD)
specialPriceTo	String	End date for the special price (YYYY-MM-DD)
cost	String	Product cost/purchase price (internal use)
minimumPrice	String	Lowest effective price — accounts for special price and variant pricing. Used for price sorting.
maximumPrice	String	Highest effective price across all variants
regularMinimumPrice	String	Regular (non-discounted) minimum price
regularMaximumPrice	String	Regular (non-discounted) maximum price
formattedPrice	String	price with currency symbol (e.g. $99.00)
formattedSpecialPrice	String	specialPrice with currency symbol
formattedMinimumPrice	String	minimumPrice with currency symbol
formattedMaximumPrice	String	maximumPrice with currency symbol
formattedRegularMinimumPrice	String	regularMinimumPrice with currency symbol
formattedRegularMaximumPrice	String	regularMaximumPrice with currency symbol
taxCategoryId	String	Tax category ID assigned to the product

Physical Dimensions

Field	Type	Description
weight	String	Product weight
length	String	Product length
width	String	Product width
height	String	Product height

Attributes

Field	Type	Description
color	String	Color attribute value (if applicable)
size	String	Size attribute value (if applicable)
brand	String	Brand attribute value (if applicable)

SEO

Field	Type	Description
metaTitle	String	SEO meta title for the product page
metaKeywords	String	SEO meta keywords
metaDescription	String	SEO meta description

Flags & Settings

Field	Type	Description
isSaleable	String	Whether the product can be purchased (1 = yes)
new	String	Whether the product is marked as "new" (1 = yes)
featured	String	Whether the product is featured (1 = yes)
visibleIndividually	String	Whether the product appears in catalog listings (1 = yes)
guestCheckout	String	Whether guest users can purchase this product (1 = yes)
manageStock	String	Whether stock is managed for this product (1 = yes)

Configurable Product Fields

Field	Type	Description
superAttributeOptions	String	JSON-encoded array of configurable attributes and their selectable options. See Configurable Products.
combinations	String	JSON-encoded object mapping variant IDs to their attribute option combinations. See Configurable Products.

Media

Field	Type	Description
baseImageUrl	String	URL of the product's primary/base image

Product Relationships Reference

These are the connection/relationship fields available on the Product type. Each returns a paginated cursor connection supporting first, last, before, and after arguments.

Core Relationships

Relationship	Return Type	Description
images	ProductImageCursorConnection	Product gallery images with id, publicPath, and position
videos	ProductVideoCursorConnection	Product videos
categories	CategoryCursorConnection	Categories the product belongs to, with translation { name }
attributeValues	AttributeValueCursorConnection	All attribute values with value and attribute { code, adminName }
attributeFamily	AttributeFamily!	The attribute family this product belongs to (not paginated)
channels	ChannelCursorConnection	Channels this product is assigned to

Variant & Configuration

Relationship	Return Type	Description
variants	ProductCursorConnection	Child variant products (for configurable products). Each variant is a full Product with its own id, name, sku, price, and attributeValues.
superAttributes	AttributeCursorConnection	The attributes used for configurable options (e.g. Color, Size)
parent	Product!	Parent product (for variant products — returns the configurable parent)

Product Type-Specific

Relationship	Return Type	Description	Dropdown Example
groupedProducts	ProductGroupedProductCursorConnection	Associated child products with qty, sortOrder, and associatedProduct details	"Get Grouped Product"
bundleOptions	ProductBundleOptionCursorConnection	Bundle option groups with selectable products and quantities	—
downloadableLinks	ProductDownloadableLinkCursorConnection	Downloadable links with price, formattedPrice, translation { title }, and sample info	"Get Downloadable Product with Samples"
downloadableSamples	ProductDownloadableSampleCursorConnection	Product-level sample files with file, fileUrl, url, and translation { title }	"Get Downloadable Product with Samples"
bookingProducts	BookingProductCursorConnection	Booking configuration with type, availableFrom, availableTo, qty, location, and type-specific slots	"Get Appointment/Rental/Default/Table/Event Booking Product"
customizableOptions	ProductCustomizableOptionCursorConnection	Custom product options (e.g. engraving text, gift wrapping)	—

Related & Recommended Products

Relationship	Return Type	Description
relatedProducts	ProductCursorConnection	Products marked as related — typically shown in a "Related Products" section on the product page
upSells	ProductCursorConnection	Up-sell products — higher-value alternatives shown on the product page
crossSells	ProductCursorConnection	Cross-sell products — complementary items shown during checkout or in the cart

Reviews

Relationship	Return Type	Description
reviews	ProductReviewCursorConnection	All reviews for this product (all statuses)
approvedReviews	ProductReviewCursorConnection	Only admin-approved reviews — use this for public-facing display

TIP

All relationship fields support cursor-based pagination with first, last, before, and after arguments. For example: images(first: 5) returns only the first 5 images. Use the nested pageInfo { hasNextPage, endCursor } to paginate through large collections.