Find products
Use product lookup when a merchant integration needs to resolve Pickware product IDs before reading stock, creating purchasing data, or building order workflows.
Available operations
- List and filter products with products.
- Load a product by global ID with product.
- Traverse variants through the
childrenfield on Product.
Identifiers
productNumberis the product number of the Shopware product. It is unique across the catalog.gtinis the GTIN (EAN) of the product. It is not unique.manufacturerNumberis the manufacturer number of the product. It is not unique.
A product with variants is a parent product in Shopware, and each variant is a product whose parentId points to it. A variant inherits the fields it leaves empty from its parent, and the API reports the inherited value: a variant without a GTIN of its own reports, and matches a filter on, the parent's GTIN. The product number is never inherited.
Example: find a product by SKU
query ProductBySku($sku: String!) {
products(filter: { productNumber: { equals: $sku } }) {
edges {
node {
id
productNumber
gtin
name
}
}
}
}
Example: resolve many SKUs at once
To resolve a list of SKUs, for example the lines of an import file, pass up to 100 of them to the in operator and request a page of the same size:
query ProductsBySkus($skus: [String!]!) {
products(first: 100, filter: { productNumber: { in: $skus } }) {
edges {
node {
id
productNumber
}
}
}
}
{
"skus": ["SHIRT-RED-M", "SHIRT-RED-L", "MUG-01"]
}
A SKU without a matching product is missing from the result instead of causing an error, so compare the returned productNumber values with your list. More than 100 values, or an empty list, are rejected; split longer lists into several requests.
Example: find products by GTIN
query ProductsByGtin($gtin: String!) {
products(first: 20, filter: { gtin: { equals: $gtin } }) {
edges {
node {
id
productNumber
gtin
name
}
}
}
}
A GTIN is not unique: Shopware accepts the same GTIN on several products, and variants without a GTIN of their own match their parent's, so the query can return more than one product. Decide in your integration what a match on several products means, for example by asking the user or by narrowing the search with the SKU. manufacturerNumber can be filtered the same way and is not unique either.
Example: read a product with its variants
Filter on the parent's product number and read its variants through children:
query ProductWithVariants($sku: String!) {
products(first: 1, filter: { productNumber: { equals: $sku } }) {
edges {
node {
id
productNumber
name
children(first: 100) {
edges {
node {
id
productNumber
gtin
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
}
}
The other way round, filter: { parentId: { equals: $parentId } } on products lists the variants of a parent with pagination, and parent on a variant leads to its parent. Keep the outer page small when you read children: the page size of a nested list multiplies with that of the list around it, and a request with products at its default page size of 10 and 100 variants each exceeds the complexity limit of a single request.
Store the returned id when the next operation needs a product reference, for example stock mutations or supplier order line items.