Cart

Here we cover key queries and mutations associated with managing a cart (selection) in Storefront API.

Cart overview

The cart is called selection in the Storefront API.

It contains details about the chosen products, applied discounts, personalized lines and a summary
Persists for 7 days
Every interaction with the selection returns the current selection state

Selection fields

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 API docs.

Line fields

The lines field represents added DisplayItems. Each line is distinguished by a unique ID.

Line uniqueness consists of such factors as the DisplayItem, Size ID, comment and price. This allows for multiple lines containing the same DisplayItem.

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
    }
  }
}

fragment SelectionBundleFragment on SelectionBundle {
  id
  type
  priceType
  sections {
    id
    quantity
    lines {
      id
      productNumber
      unitPrice {
        formattedValue
      }
    }
  }
}

In the subsequent sections, we'll explore specific mutations and queries that can be performed on the selection.

Add displayItem/bundle to selection

Depending on the Overselling Prevention configuration of the store the ability to add DisplayItems to a selection can vary. It may include any DisplayItem or exclusively those with available stock. The following two mutations can be used to add a DisplayItem to a 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 (API docs)

addFlexibleBundle mutation accepts only flexible bundles. (API docs)

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

Update selection line

The updateLine mutation (API docs) 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
    }
  }
}

Delete selection line

The deleteLine mutation (API docs) 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
    }
  }
}

Remove subscription plan from line

In addition to the option of removing a line subscription plan using the updateLine mutation with a value of 0, the Storefront API provides a specialized mutation, removeSubscriptionPlanFromLine (API docs), 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
    }
  }
}

Set/unset selection attributes

In the Storefront API, setting selection attributes allows for the preservation of these attributes on a finalized order after it has been placed (API docs). The Storefront 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 (API docs).

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
    }
  }
}

Claim selection

Prefilled selections in AMS, accompanied by a generated selection link, can be integrated into a shopper's session using the claimSelection mutation in the Storefront API (API docs). 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
    }
  }
}

Set affiliate

If a shopper arrives at the site through an affiliate link, connect it to the selection by calling the setAffiliate mutation (API docs). 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
    }
  }
}

Set campaign site

If a shopper accesses the site through a campaign site link, submit it to the Storefront API by calling the setCampaignSite mutation (API docs). 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
    }
  }
}

Set selection

To attach an existing selection to a shopper’s session, call the setSelection mutation (API docs).

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

Cart overview​

Add displayItem/bundle to selection​

Update selection line​

Delete selection line​

Remove subscription plan from line​

Set/unset selection attributes​

Claim selection​

Set affiliate​

Set campaign site​

Set selection​