Selection Handling

Last updated October 21st at 12:46pm

Introduction#

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:

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

mutation {
  setSelection(id: "dc6265d9c4ea00945f72328b122b2a66") {
    selection {
      ...SelectionFragment
    }
    userErrors {
      message
      path
    }
  }
}