Product information
Last updatedIntroduction#
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
"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".
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
query {
displayItems(
where: {
search: "Summer"
searchInFields: [COLLECTION_NAME]
}
page: 1
limit: 40
) {
list {
...DisplayItemFields
}
filters {
...FilterFields
}
pagination {
...PaginationFields
}
userErrors {
message
path
}
}
}
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.
1
2
3
4
5
6
7
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
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.