Skip to main content

Complete Item filter expression reference

The Complete Item Query API accepts an optional filter.expression argument on the completeItems query. This is the recommended, general-purpose way to filter Complete Items — all other filter fields except expression, includeDeleted and includeParents are deprecated in favor of it.

query {
  completeItems(first: 10, businessUnitId: "STORE_A", filter: {
    expression: "status: ACTIVE AND brand.keyword: PnP"
  }) {
    nodes {
      id
      name
    }
  }
}

This page covers what's specific to Complete Item: the fields you can reference, and a couple of field-naming quirks. For the KQL syntax itself — operators, escaping, case sensitivity, dates, grouped matching — see Filter expression syntax (KQL).

Complete Item still accepts the older, no-longer-required extra level of escaping mentioned on that page, for backward compatibility with existing integrations. New integrations should use the plain escaping shown there.

IMPORTANT NOTE:

One field is named differently in expression than in the rest of the schema. When reading an item, the GraphQL schema calls this field assortmentPolicyType. In expression, use assortmentType instead — e.g. assortmentType: IN_ASSORTMENT. Using assortmentPolicyType in expression doesn't error, it just silently matches nothing. Every other field name below is the same in expression as it is in the schema.

Field reference​

These are the fields you can reference in expression, matching the completeItems result type in the GraphQL schema, grouped by shape.

Top-level fields​

id, globalUniqueId, parentId, businessUnitGroupId, businessUnitIds, businessUnitHierarchyLevel (long), name, description, brand, status, type, itemCategoryId, assortmentType (called assortmentPolicyType when reading item data — see the note above), assortmentTags, assortmentFrom (date), assortmentTo (date), conditionIds, tags, depositAndFeeRuleIds, salesUnitOfMeasurement, referencePriceUnitOfMeasurement, referencePriceConversionFactor (float), netContent (double), revision (long), correlationId, created / createdBy (date / text), modified / modifiedBy (date / text), availableInPos / needsApproval / needsLabelPrinting / needsManualSending (boolean).

List-of-value fields (businessUnitIds, assortmentTags, tags, depositAndFeeRuleIds, conditionIds) behave like any other field — a match against any element in the list matches the item.

List fields — grouped matching​

additionalProperties, itemIdentifiers, and priceSpecifications (as well as the additionalProperties list inside each itemIdentifiers entry and inside each priceSpecifications entry) are lists of objects that support the grouped-matching syntax, field: { ... }, to match conditions against a single entry in the list.

additionalProperties (top-level): id, name, code, description, dataType, value, isMandatory (boolean)

itemIdentifiers: id, itemId, globalUniqueId, value, normalizedGtin, type, status, isPrimary (boolean), gtinPrefixType, gs1IssuingCountryCode, conditionIds, name, description, businessUnitIds, businessUnitGroupId, businessUnitHierarchyLevel (long), revision (long), correlationId, created / createdBy, modified / modifiedBy, and its own additionalProperties list (same shape as above).

priceSpecifications: id, itemId, globalUniqueId, type, status, value (double), minPrice / maxPrice (double), currencyId, validFrom / validTo (date), isCurrent / isMandatory / excludingTax (boolean), taxableGroupId, promotionId, discountIds, conditionIds, name, description, businessUnitIds, businessUnitGroupId, businessUnitHierarchyLevel (long), revision (long), correlationId, created / createdBy, modified / modifiedBy, and its own additionalProperties list.

images — grouped matching not supported​

images (heightInPixels, widthInPixels, intendedAudience, size, url, modified) is also a list field, but unlike the fields above it does not support the field: { ... } grouped-matching syntax — see Limitations below.

Working examples​

Matching one additional property with id: Color, value: Blue and another with id: Size and value of S or M:

additionalProperties: { id: Color AND value: Blue } AND additionalProperties: { id: Size AND (value: S OR value: M) }

itemIdentifiers combined with NOT, a .keyword wildcard, and the conditionIds field:

itemIdentifiers: { NOT type: (GTIN13 GTIN14) AND value.keyword: aiid* AND conditionIds: PROMO-EXCLUSIVE }

priceSpecifications combined with numeric ranges, a date range, and a boolean:

priceSpecifications: { isCurrent: true AND type: SALES AND minPrice >= 5 AND maxPrice <= 20 AND validFrom <= 2026-07-17 AND conditionIds: SEASONAL }

Matching an additional property that belongs to a specific item identifier requires the full path — a group inside a group:

itemIdentifiers: { additionalProperties: { id: Grade AND value: A } }

Combining a top-level condition with two independent grouped conditions:

brand: PnP AND additionalProperties: { id: Color AND value: Green } AND additionalProperties: { id: Size AND (value: 36 OR value: 37) }

Limitations​

Also see the limitations that apply to every API.

  1. images doesn't support grouped matching. Unlike additionalProperties, itemIdentifiers, and priceSpecifications, the images: { ... } syntax fails with a query error against it. Writing separate conditions instead (images.size: L AND images.url: img-B) does not error, but the conditions are evaluated independently and can each match a different image entry — so a result doesn't guarantee both conditions hold for the same image.
  2. assortmentType vs assortmentPolicyType. Use assortmentType in expression — the schema's assortmentPolicyType field name doesn't work here and matches nothing, silently. See the note near the top of this page.
  3. Deprecated filter fields combine additively. If you supply both expression and any deprecated filter field (businessUnitGroupId, businessUnitId, itemIds, status, itemCategoryId, assortmentPolicyType, assortmentTags), they are AND-ed together — mixing them can produce confusing double-filtering. Migrate fully to expression.
  4. Result cap. completeItems returns at most 9,999 results (first/pagination ceiling), independent of how narrow or broad expression is.

See also​