Product information

Last updated January 21st at 3:18pm

Introduction#

This documentation is designed to help developers understand the structure and functionalities related to product information retrieval in the DTC API, including product listing, filtering, sorting, searching and details page.

Product content#

In the DTC API, both individual products and bundles are represented by the DisplayItem type. DisplayItem is a product variant that’s been activated on a store display in the AMS backend or via API. You can activate more than one variant on each Display, resulting in a DisplayItem for each. This type encapsulates all the necessary product information, including descriptions, sizes, prices, and media assets.

DisplayItem fields

The following example illustrates the various product content that can be fetched using the DTC API:

fragment DisplayItemFields on DisplayItem {
  id
  createdAt
  modifiedAt
  available
  hasStock
  brand {
    name
  }
  category {
    name
  }
  canonicalCategory {
    name
  }
  canonicalUri
  collection {
    name
  }
  description {
    formatted
    raw
  }
  sizeChart {
    name
    horizontalLabels
    verticalLabels
    dividerSymbol
    displayUnit
    localization {
      displayName
      horizontalLabels
      verticalLabels
      countries {
        code
      }
    }
  }
  language {
    code
    name
  }
  market {
    id
    name
  }
  pricelist {
    id
    name
  }
  items {
    id
    name
    GTIN
    productSizeId
    preorder
    sizeLocalization {
      name
      displayName
      countries {
        code
      }
    }
    sku
    stock {
      available
    }
    horizontalLabelIndex
    verticalLabelIndex
  }
  bundle {
    id
    type
    priceType
    sections {
      id
      quantity
      items {
        ...PreviewDisplayItemFields
      }
    }
    minPrice {
      value
      formattedValue
    }
    maxPrice {
      value
      formattedValue
    }
  }
  attributes(keys: []) {
    ...AttributeFields
  }
  media(keys: []) {
    ...MediaFields
  }
  metaDescription
  metaKeywords
  metaTitle
  minimumOrderQuantity
  name
  orderQuantityDenominator
  price {
    value
    formattedValue
  }
  originalPrice {
    value
    formattedValue
  }
  lowestPrice {
    price {
      value
      formattedValue
    }
    originalPrice {
      value
      formattedValue
    }
    periodDays
  }
  isPrimaryVariant
  productVariant {
    name
    number
  }
  relatedDisplayItems(relationType: "standard") {
    relation
    displayItems {
      ...PreviewDisplayItemFields
    }
  }
  shortDescription {
    formatted
    raw
  }
  showAsNew
  showAsSale
  uri
  weight
  weightUnit
  subscriptionPlans {
    id
    name
    interval {
      value
      type
    }
    discount
  }
}
fragment MediaFields on MediaByKey {
  key
  media {
    url
    width
    height
    mimeType
    attributes(keys: []) {
      ...AttributeFields
    }
  }
}
fragment AttributeFields on Attribute {
  type {
    name
  }
  ... on MappedAttribute {
    id
  }
  elements {
    key
    kind
    ... on AttributeChoiceElement {
      value {
        name
        value
      }
      values {
        name
        value
      }
    }
    ... on AttributeImageElement {
      url
      width
      height
      mimeType
    }
    ... on AttributeFileElement {
      url
    }
    ... on AttributeStringElement {
      value
      translations {
        language {
          name
        }
        value
      }
    }
  }
}
fragment PreviewDisplayItemFields on DisplayItem {
  id
  name
  uri
  media(keys: []) {
    ...MediaFields
  }
  price {
    value
    formattedValue
  }
  originalPrice {
    value
    formattedValue
  }
  showAsSale
  showAsNew
}

Most fields are self-descriptive, but let's highlight some crucial ones:

Field	Description
displayItem.id	Unique identifier for the DisplayItem. Can be used to get DisplayItem via displayItem query or to filter in displayItems query
displayItem.uri	URI for the DisplayItem. Can be used to get DisplayItem via lookupUri mutation
displayItem.sizeChart	Size chart representation. Can be used to build size chart on a page along with localizations. Each displayItem.items can be fit into it by provided horizontal and vertical indexes.
displayItem.items	Represents available and buyable sizes of a DisplayItem. Item id is an identifier that is used to add a product to a selection. That type also contains horizontalLabelIndex and verticalLabelIndex that locate the item on a sizechart.
displayItem.bundle	Information related to bundles. You can find bundle and price types there along with sections content and pricing. Min and max prices are provided only for flexible bundles with dynamic pricing, for others price is static and can be found under displayItem.price
displayItem.price	Price with discounts for current market and pricelist in session mode or if one market and pricelist is provided in no session mode. For flexible bundles with dynamic prices the value is null because price cannot be defined without selected section items.
displayItem.originalPrice	Price before discount.
displayItem.attributes	List of product attributes. Includes product, display, variation and storeItem attributes.

If there are any DisplayItem translations for a session language or the one provided in no session mode, they are applied on DisplayItem fields automatically to provide the shopper information in the desired language.

Attributes

DTC API introduces a new format for attributes providing extended information about an attribute and its elements. An example response of a mapped attribute with a boolean element type:

{
    "type": {
        "name": "pr_limited_edition_mapped"
    },
    "id": 31,
    "elements": [
        {
            "key": "bool",
            "kind": "BOOLEAN",
            "value": {
                "name": "Yes",
                "value": "1"
            },
            "values": [
                {
                    "name": "No",
                    "value": "0"
                },
                {
                    "name": "Yes",
                    "value": "1"
                }
            ]
        }
    ]
}

To transform attributes to a Checkout API format, concatenate type.name and each elements.key with an underscore and use the specific element value (URL for image and file, value for string and choice element types). For example, for the provided attribute, the Checkout API format is pr_limited_edition_mapped_bool: "1".

Product listing#

To build a product listing page, use the displayItems query with various filtering options, pagination, and full-text search.

DisplayItems query example

query DisplayItems {
  displayItems(page: 1, limit: 20) {
    list {
      ...DisplayItemFields
    }
    filters {
      ...FilterFields
    }
    pagination {
      ...PaginationFields
    }
    userErrors {
      message
      path
    }
  }
}
fragment FilterFields on FilterOption {
  key
  anyAvailable
  selectedValues
  values {
    active
    count
    filterCount
    totalCount
    value
    ... on BrandFilterValue {
      brand {
        name
      }
    }
    ... on CategoryFilterValue {
      category {
        name
      }
    }
    ... on CollectionFilterValue {
      collection {
        name
      }
    }
    ... on MappedAttributeFilterValue {
      attribute {
        ...AttributeFields
      }
    }
    ... on SizeNameFilterValue {
      sizeLocalization {
        name
        displayName
        countries {
          code
        }
      }
    }
    ... on TextFilterValue {
      name
    }
  }
}
fragment PaginationFields on PaginationInfo {
  hasPreviousPage
  hasNextPage
  nextPage
  previousPage
  currentPage
  lastPage
  limit
}

In case you need to list category DisplayItems, use the lookupURI mutation providing category URI. It also supports filtering and pagination for category DisplayItems.

LookupURI mutation example

mutation LookupURI {
  lookupUri(
    uri: "case1"
    for: [CATEGORY]
  ) {
    found
    ... on CategoryUriLookupPayload {
      category {
        name
      }
      displayItemList {
        displayItems {
          ...DisplayItemFields
        }
        filters {
          ...FilterFields
        }
        pagination {
          ...PaginationFields
        }
      }
    }
  }
}

The query offers pagination information under displayItems.pagination with each call, supporting the creation of an efficient PLP. When retrieving the next set of DisplayItems, you need to use the pagination.nextPage value for the page query argument. Similarly, pagination.previousPage is used to get the previous set of DisplayItems.

DTC API imposes limits on the number of DisplayItems that can be fetched per call, allowing 40 DisplayItems for session mode and 100 for no session mode.

Product filtering#

The DTC API offers a comprehensive set of filter options accessible under displayItems.filters in each call. Various filter types, such as categories, collections, and brands, are available, each presenting a detailed overview of the filtered options. For instance, the category filter type includes the filters.values.category field, which signifies the filtered category. This enables you to retrieve category information without the need for a separate query.

Consider a scenario where a displayItems query returns the following filter for DisplayItems:

{
    "key": "categories",
    "anyAvailable": true,
    "selectedValues": [],
    "values": [
        {
            "active": false,
            "count": 31,
            "filterCount": 31,
            "totalCount": 31,
            "value": "1",
            "category": {
                "name": [
                    "Shop"
                ]
            }
        },
        {
            "active": false,
            "count": 20,
            "filterCount": 20,
            "totalCount": 20,
            "value": "3",
            "category": {
                "name": [
                    "Shop",
                    "Women"
                ]
            }
        },
        {
            "active": false,
            "count": 11,
            "filterCount": 11,
            "totalCount": 11,
            "value": "4",
            "category": {
                "name": [
                    "Shop",
                    "Men"
                ]
            }
        }
    ]
},
{
    "key": "collections",
    "anyAvailable": true,
    "selectedValues": [],
    "values": [
        {
            "active": false,
            "count": 5,
            "filterCount": 5,
            "totalCount": 5,
            "value": "0",
            "collection": null
        },
        {
            "active": false,
            "count": 10,
            "filterCount": 10,
            "totalCount": 10,
            "value": "1",
            "collection": {
                "name": "Summer"
            }
        },
        {
            "active": false,
            "count": 16,
            "filterCount": 16,
            "totalCount": 16,
            "value": "2",
            "collection": {
                "name": "Winter"
            }
        }
    ]
}

The provided example filter contains an information about each category filter option:

Field	Description
filters.key	Key name you can use to apply filter
filters.anyAvailable	Shows if there are any matches with current filtering
filters.selectedValues	List of applied filter values
filters.values.active	Shows if filter is applied or not
filters.values.count	Number of matches with the current filtering
filters.values.filterCount	Number of matches with the current filtering when you discount the other selected values in this group.
filters.values.totalCount	The number of items in total available, independent of filtering
filters.values.value	Value you can use to apply filter

To filter DisplayItems by a "Shop/Women" category and “Summer” collection, you need to add the filter key and value to the displayItems query. These values can be found under filters.key and filters.values.value. For the category, the key is "categories" and the value is "3" while for the collection, the key is "collections" and the value is "1".

query {
    displayItems(
        where: {
            filters: [
                { key: "categories", values: ["3"] }
                { key: "collections", values: ["1"] }
            ]
        }
        page: 1
        limit: 20
    ) {
        list {
            ...DisplayItemFields
        }
        filters {
            ...FilterFields
        }
        pagination {
            ...PaginationFields
        }
        userErrors {
            message
            path
        }
    }
}

As a result, DTC API return only 7 display items that are assigned to the “Shop/Women” category and “Summer” collection. Filter options are also changed, as two filters are already applied. Let’s assume we now want to filter returned products by an additional “Shop/Men” category. DTC API returned the following list of category filter options:

{
    "key": "categories",
    "anyAvailable": true,
    "selectedValues": [
        "3"
    ],
    "values": [
        {
            "active": false,
            "count": 7,
            "filterCount": 10,
            "totalCount": 31,
            "value": "1",
            "category": {
                "name": [
                    "Shop"
                ]
            }
        },
        {
            "active": true,
            "count": 7,
            "filterCount": 7,
            "totalCount": 20,
            "value": "3",
            "category": {
                "name": [
                    "Shop",
                    "Women"
                ]
            }
        },
        {
            "active": false,
            "count": 0,
            "filterCount": 3,
            "totalCount": 11,
            "value": "4",
            "category": {
                "name": [
                    "Shop",
                    "Men"
                ]
            }
        }
    ]
}

Category filter option with value "4" now has updated count value, because of the updated filter results.

Field values.count: Represents the number of matches with the current results. A zero here means none of the “Shop/Men” category products are present in items returned by the previously applied “Shop/Women” and “Summer” category filters.

Field values.filterCount: Provides the number of matches for that filter and other applied filter types. A count of three means there are 3 display items assigned to the “Shop/Men” category that are also in the “Summer” collection.

Field values.totalCount: Indicates the total number of items available for that filter. An eleven here means there are 11 items in the “Shop/Men” category.

As a result, when adding one more filter to the displayItems query with a key "categories" and value "4" the number of items returned is 10, including three additional display items from the “Shop/Men” category.

Applying a filter in the DTC API results in returning only DisplayItems that meet the filter criteria. Providing multiple filter values is treated as an OR operation, returning products that meet at least one of the filter criteria. When applying multiple filters, they function as an AND operation, returning only products that meet all filter criteria.

Product sorting#

The DisplayItems query supports sorting by various fields. To implement this, include the sort query parameter with a list of fields and the preferred order for sorting. The DTC API allows sorting by multiple fields, respecting the priority assigned to the provided sort fields and applying them in the specified order. In the following example, DisplayItems are initially sorted by price. In cases where prices are identical for multiple products, the sorting is further based on the createdAt date.

query {
  displayItems(
    sort: [
      { key: PRICE, order: DESC }
      { key: CREATED_AT, order: DESC }
    ]
    page: 1
    limit: 40
  ) {
    list {
      ...DisplayItemFields
    }
    filters {
      ...FilterFields
    }
    pagination {
      ...PaginationFields
    }
    userErrors {
      message
      path
    }
  }
}

Product search#

The DTC API allows you to build a search bar on a page, offering both strict and full-text search options. Full-text search is performed by providing only the search query parameter. In this scenario, the DTC API seeks a strict match or prefix in various fields, returning DisplayItems that contain the provided phrase.

Alternatively, you can perform a search on specified fields. To achieve this, you need to include the searchInFields query parameter along with the search parameter. In this case, only products with matches in the specified fields are returned. DTC API supports the following search options:

NAME
FUZZY_NAME
BRAND_NAME
COLLECTION_NAME
PRODUCT_VARIANT_NAME
FUZZY_PRODUCT_VARIANT_NAME
PRODUCT_NUMBER
SIZE_NUMBER
GTIN
SHORT_DESCRIPTION
DESCRIPTION
CATEGORY_NAME

It's worth noting that some fields have the prefix "FUZZY," indicating that the search is not strict. This means that even if the search query partially matches the field content, it will still be included in the results.

query {
  displayItems(
    where: { 
      search: "Summer"
      searchInFields: [COLLECTION_NAME] 
    }
    page: 1
    limit: 40
  ) {
    list {
      ...DisplayItemFields
    }
    filters {
      ...FilterFields
    }
    pagination {
      ...PaginationFields
    }
    userErrors {
      message
      path
    }
  }
}

Product details page#

To present detailed product content on a PDP, you have two options: The first option is to use the displayItem query, which requires providing a DisplayItem ID.

query DisplayItems {
  displayItem(
    id: 1
  ) {
    ...DisplayItemFields
  }
}

The second option is to utilize the lookupUri mutation. For this option, you need to provide a DisplayItem URI and specify DISPLAY_ITEM as the lookup type.

mutation {
  lookupUri(
    uri: "white-t-shirt"
    for: [DISPLAY_ITEM]
  ) {
    found
    ... on DisplayItemUriLookupPayload {
      displayItem {
        ...DisplayItemFields
      }
    }
  }
}

Both options support DisplayItem translations. For session mode the language is taken from the session. In no session mode, providing languageCode is the only way to obtain DisplayItem translations in the desired language. Provided URI should be in the current session language or match translations from a languageCode in no session mode.

Additionally, in no session mode, you can specify the market and pricelist. Only prices for the provided markets and pricelists are returned in this case. If only one market and pricelist are provided, the price is selected for the DisplayItem and can be found under displayItem.price.