Skip to main content

Understanding cart item flattening

Cart item flattening is a process that splits each cart item whose quantity is greater than 1 into individual cart items.

Talon.One always flattens the cart items you send. This enables it to apply per-item effects to units of a given product, instead of only considering all the units of a given product.

For example, if you run a clothing company and a customer adds two T-shirts and three hats to their cart, Talon.One flattens the cart items as follows:

Non-flattened cart items vs. flattened cart items.
note
  • As of July 2025, you can no longer use the Item.Quantity attribute in per-item effects in Applications that have cart item flattening enabled.
  • Talon.One applies per-item discounts to each instance of the item. Using per-item effects can lead to more triggered effects.

JSON representation of the flattening​

Use the Update customer session endpoint to share the details of a session, and its cart items, to Talon.One.

Cart items are represented by the cartItems array inside the payload. For example, if a customer adds 3 units of a given item to their cart, you send the following payload to Talon.One:

Your payload
{
  "customerSession": {
    "profileId": "URNGV8294NV",
    // ...
    "state": "open",
    "cartItems": [
      {
        "name": "Candle",
        "sku": "SKU1241028",
        "quantity": 3,
        "price": 15.99,
      }
    ]
}

Talon.One processes the cart as follows:

Internal version of your payload
{
  "customerSession": {
    "profileId": "URNGV8294NV",
    // ...
    "state": "open",
    "cartItems": [
      {
        "name": "Candle",
        "sku": "SKU1241028",
        "quantity": 1,
        "price": 15.99,
      },
      {
        "name": "Candle",
        "sku": "SKU1241028",
        "quantity": 1,
        "price": 15.99,
      },
      {
        "name": "Candle",
        "sku": "SKU1241028",
        "quantity": 1,
        "price": 15.99,
      },
    ]
}

As a result, if you use per-item effects, like a per-item discount applied to all items of the session, you receive three effects instead of one.