Skip to main content

Returning individual items

Let's return some items from a given customer session.

We do this by calling the Return cart items. endpoint. This endpoint automatically changes the session state from closed to partially returned, and we can expect rollback effects to be triggered.

Returning cart items depends on whether cart item flattening is enabled, because the way we identify the items to be returned in the payload is different. In this tutorial, we will cover both cases.

Before following this tutorial, we recommend that you:

Let's imagine that our customer purchased 1 pair of shoes and 2 units of the same shirt. The customer session is closed because the checkout step is complete, and it contains the following cart items:

Cart items in the customer session
"cartItems": [
  {
    //...
    "name": "shoes1",
    "sku": "9696",
    "quantity": 1,
    "price": 60,
    "category": "shoes"
  },
  {
    //...
    "name": "shirts3",
    "sku": "6478",
    "quantity": 2,
    "price": 20,
    "category": "shirts"
  }
]

This session is part of a campaign that gives a $5 discount per item. As with all per item effects, we must consider the cart item flattening setting.

After the purchase, our customer wants to return one discounted shirt.

Returning an item with cart item flattening enabled​

Let's consider that cart item flattening is enabled. In this case, the 2 items in the cart are flattened into 3 items.

The Update customer session request that closed the customer session during checkout returned the following discount effects:

Applied discount effects (cart item flattening enabled)
{
  //...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "5forALL",
    "value": 5,
    "position": 0, // the pair of shoes
    "subPosition": 0
  }
},
{
  //...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "5forALL",
    "value": 5,
    "position": 1, // the shirts
    "subPosition": 0 // the first shirt
  }
},
{
  //...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "5forALL",
    "value": 5,
    "position": 1, // the shirts
    "subPosition": 1 // the second shirt
  }
}

If the customer wants to return a shirt, we return the item in position 1, subposition 0.

Let's use the Return cart items endpoint to create a return request for one of the shirts in the cart. When cart item flattening is enabled, we can use the quantity optional property to indicate how many units of a given item we want to return. The request contains the following body:

Return request (cart item flattening enabled)
{
  "return":{
    "returnedCartItems": [
      {
        "position": 1, // cart item to partially return
        "quantity": 1 // number of units to return
      }
    ]
  }
}
note

We can also return items directly in the Campaign Manager.

If we do this, we still have to take care of any expected rollback effects.

Because of the return request, we receive a rollbackDiscount effect to undo the discount effect applied during the closing of the session. For the item we returned, we get the following effects array in the response:

Rollback effect (cart item flattening enabled)
{
  "effects": [
    {
      //...
      "effectType": "rollbackDiscount",
      "props": {
        "name": "5forALL",
        "value": 5,
        "cartItemPosition": 1,
        "cartItemSubPosition": 0
      }
    }
  ]
}

The session state automatically changes from closed to partially returned, and the impact of the effect on any campaign budgets is reverted.

At this point, the rest of the workflow happens in our e-commerce app, where we would apply the necessary steps to refund the correct amount.

Returning an item with cart item flattening disabled​

Let's consider that cart item flattening is disabled. In this case, we only have 2 items in the cart.

The Customer session update request that closed the customer session during checkout returned the following discount effects:

Applied discount effects (cart item flattening disabled)
{
  //...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "5forALL",
    "value": 5,
    "position": 0 // the pair of shoes
  }
},
{
  //...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "5forALL",
    "value": 5,
    "position": 1 // the shirts
  }
}

If the customer wants to return a shirt, we have to return the 2 shirts (item in position 1).

Let's use the Return cart items endpoint to create a return request for both shirts in the cart. The request contains the following body:

Return request (cart item flattening disabled)
{
  "return":{
    "returnedCartItems": [
      {
        "position": 1 // cart item to return
      }
    ]
  }
}
note

We can also return items directly in the Campaign Manager.

Because of the return request, we receive a rollbackDiscount effect to undo the discount effect applied during the closing of the session. For the item we returned, we get the following effects array in the response:

Rollback effect (cart item flattening disabled)
{
  "effects": [
    {
      //...
      "effectType": "rollbackDiscount",
      "props": {
        "name": "5forALL",
        "value": 5,
        "cartItemPosition": 1
      }
    }
  ]
}

The session state automatically changes from closed to partially returned, and the impact of the effect on any campaign budgets is reverted.

At this point, the rest of the workflow happens in our e-commerce app, where we would apply the necessary steps to refund the correct amount.