Selection Handling
Last updatedIntroduction#
This documentation dives into the key queries and mutations associated with selection handling in DTC API. Whether you're adding products, updating lines, or associating an affiliate, this guide offers detailed explanations and examples to streamline your integration with the DTC API.
Selection overview#
Selections are a fundamental aspect of the DTC API, capturing crucial information about a shopper's decisions on the site. It holds details about the chosen products, applied discounts, personalized lines and a basket summary.
The Selection lives for a duration of 7 days, after which it expires. This lifespan ensures that the user's preferences and choices remain during their browsing and actions within this timeframe.
Every interaction with the selection, be it through queries or mutations, yields the current selection state, offering a snapshot of the user's choices. This information is critical in seamless navigation, efficient order processing and personalized shopping journey.
Selection fields
Let's delve into the key fields encapsulated within the selection state:
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
fragment SelectionFragment on Selection {
id
lines {
...LineFragment
}
grandTotal {
value
formattedValue
}
language {
name
code
}
discounts {
name
appliedOn
method
type
value {
value
formattedValue
}
... on CodeVoucher {
code
}
... on UrlVoucher {
url
}
}
attributes {
type {
name
}
elements {
key
kind
... on AttributeChoiceElement {
value {
name
value
}
values {
name
value
}
}
... on AttributeFileElement {
url
}
... on AttributeImageElement {
url
width
height
mimeType
}
... on AttributeStringElement {
value
translations {
language {
name
code
}
value
}
}
}
... on MappedAttribute {
id
}
}
}
| Field | Description |
|---|---|
| selection.id | ID of the current selection. Can be nullable if the selection is not saved yet. |
| selection.lines | Selection lines containing added DisplayItems, each with information about the product, variant, size, etc. |
| selection.grandTotal | Grand total representing the selection summary without applied taxes, ideal for a mini cart. |
| selection.language | Pre-selected or set language on a selection. |
| selection.discounts | List of applied vouchers on the selection, excluding voucher values applied on lines. |
| selection.attributes | List of selection attributes set by the setSelectionAttributes mutation or existing on the master selection for claimed selections. |
| selection.checkout | Selection fields that are needed on the checkout stage. Described in [link to checkout docs]. |
A crucial component of every selection is the lines field, representing added DisplayItem and selected Item on it. Each line is distinguished by a unique ID.
Line uniqueness consists of such factors as the DisplayItem, Size ID, comment and price. This design allows for the possibility of multiple lines featuring the same DisplayItem under distinct conditions, providing flexibility and granularity in representing various product configurations within the selection.
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
fragment LineFragment on Line {
id
name
productVariantName
size
productNumber
comment
addedFromCategory {
id
name
}
productExternalUrl
brand {
name
}
item {
id
name
sku
GTIN
preorder
stock {
available
}
}
appliedPromotions {
type
percent
value {
value
formattedValue
}
}
hasDiscount
unitPrice {
value
formattedValue
}
unitOriginalPrice {
value
formattedValue
}
quantity
subscriptionId
displayItem {
id
}
... on BundleLine {
bundle {
...SelectionBundleFragment
}
}
}
In the subsequent sections, we'll explore specific mutations and queries that can be performed on the selection, empowering you to create a seamless and user-centric shopping experience.
Add displayItem/bundle to selection
Based on the Overselling Prevention configuration of the store, the ability to add DisplayItems to a selection can vary. It can include any DisplayItem or exclusively these with available stock. The following two mutations can be used to add DisplayItem to selection:
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
mutation {
addItem(item: "1-1") {
line {
...LineFragment
}
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
addFlexibleBundle(item: "10-1", sections: [
{
sectionId: 1
item: "2-2"
}
{
sectionId: 2
item: "3-1"
}
]) {
line {
...LineFragment
}
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}
addItem mutation accepts products and fixed bundles
addFlexibleBundle mutation accepts only flexible bundles.
Both mutations accept various input parameters:
| Parameter | Description |
|---|---|
| Item | Item ID from displayItem.items.id. Expected format: {displayItemID}-{productSizeID}. |
| quantity | Number of products to be added (default value is 1). |
| categoryId | Category ID that the product was added from (appears on line.addedFromCategory). |
| productExternalUrl | URL that the product was added from (appears on line.productExternalUrl). |
| comment | Additional comment on the line (appears on line.comment and makes the line unique). |
| subscriptionPlan | Subscription plan ID to be used on a created subscription. |
| localizedProdSize | Localized size and localization definition name that appear on a selection or finalized order line. |
| addFlexibleBundle.sections | List of items selected on each bundle section. |
When the selection already includes the same item ID, the system updates the existing line rather than adding a new one. However, if there are variations in price, comment, or subscription plan, two distinct lines are retained within the selection. This ensures accurate tracking and management of items with different details.
It is crucial not to overlook any errors returned for a mutation, as they result in the selection remaining unmodified
The updateLine mutation empowers you to modify any selection line, whether it be the quantity, subscription plan ID, or comment. Simply provide the lineId along with the desired update options.
Notably, setting the quantity to 0 within this mutation mirrors the behavior of the deleteLine mutation, offering flexibility in choosing your preferred approach.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
updateLine (
lineId: "608bf7956e1e20e8e36c8736d88a02e9"
quantity: 2
subscriptionPlanId: 1
comment: "test"
) {
selection {
... SelectionFragment
}
userErrors {
message
path
}
}
}
The deleteLine mutation provides the flexibility to remove any line from a selection, with the exception of a free product line added by a voucher when the "Allow customer to remove product" setting is configured to No.
1
2
3
4
5
6
7
8
9
10
11
12
13
mutation {
deleteLine (
lineId: "608bf7956e1e20e8e36c8736d88a02e9"
) {
selection {
... SelectionFragment
}
userErrors {
message
path
}
}
}
In addition to the option of removing a line subscription plan using the updateLine mutation with a value of 0, the DTC API provides a specialized mutation, removeSubscriptionPlanFromLine, specifically designed for this purpose. This dedicated mutation enhances clarity and simplifies the process of removing subscription plans from selection lines, offering a more intuitive approach to manage subscription-related updates.
1
2
3
4
5
6
7
8
9
10
11
12
13
mutation {
removeSubscriptionPlanFromLine(
lineId: "608bf7956e1e20e8e36c8736d88a02e9"
) {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}
In the DTC API, setting selection attributes allows for the preservation of these attributes on a finalized order after it has been placed. The DTC API plugin features an order attribute selector, where any selected attributes are exposed in the API and can be configured for the selection.
For dynamic attributes, it is necessary to provide the attribute and element names, along with the value to be set.
For mapped attributes, only the ID is required.
To remove any attribute set on the selection, the unsetSelectionAttributes mutation can be utilized.
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
mutation {
setSelectionAttributes(
dynamicAttributes: [
{
attributeTypeName: "card"
attributeElementKey: "message"
attributeElementValue: "We Appreciate All You Do"
}
]
mappedAttributes: [{ attributeId: 15 }]
) {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
unsetSelectionAttributes(
dynamicAttributes: [
{ attributeTypeName: "card", attributeElementKey: "message" }
]
mappedAttributes: [{ attributeId: 15 }]
) {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}
Prefilled selections in AMS, accompanied by a generated selection link, can be integrated into a shopper's session using the claimSelection mutation in the DTC API. This feature allows the claimed selections to be utilized multiple times until one of them is eventually finalized.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
mutation claimSelection {
claimSelection(
id: "6464df5118a97c144d853f6e54520256"
hash: "0f67ffbdefefd2dbc3f1927909812ac3"
) {
selection {
... SelectionFragment
}
userErrors {
message
path
}
}
}
If a shopper arrives at the site through an affiliate link, connect it to the selection by calling the setAffiliate mutation. The affiliate information is stored in the session, ensuring that the affiliate remains linked to all selections made by the shopper until it expires.
1
2
3
4
5
6
7
8
9
10
11
mutation {
setAffiliate(uri: "https://example.com") {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}
If a shopper accesses the site through a campaign site link, submit it to the DTC API. Upon processing this call, the selection market is changed, revealing specific market prices to the shopper.
1
2
3
4
5
6
7
8
9
10
11
mutation {
setCampaignSite(uri: "https://example.com") {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}
To attach an existing selection to a shopper’s session, call the setSelection mutation.
1
2
3
4
5
6
7
8
9
10
11
mutation {
setSelection(id: "dc6265d9c4ea00945f72328b122b2a66") {
selection {
...SelectionFragment
}
userErrors {
message
path
}
}
}