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.

note

Before following this tutorial, we recommend that you read about customer session states.

Let's imagine that our customer purchased 1 pair of shoes and 2 units of the same shirt. With cart item flattening, identical products are viewed as single items in the cart. So, we have a total of 3 items in our cart.

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.

After the purchase, our customer wants to return 1 discounted shirt out of the 3 items.

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

Applied discount effects
{
  //...
  "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. 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
{
  "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
{
  "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 apply the necessary steps to refund the correct amount.