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:
- Ensure you know if cart item flattening is enabled in your Application.
- Read the generic explanation about customer session states.
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:
"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:
{
//...
"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":{
"returnedCartItems": [
{
"position": 1, // cart item to partially return
"quantity": 1 // number of units to return
}
]
}
}
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:
{
"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:
{
//...
"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":{
"returnedCartItems": [
{
"position": 1 // cart item to return
}
]
}
}
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:
{
"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.