Skip to main content
Check the complete list of parameters and responses of the POST Reverse coupon endpoint to reverse a coupon redemption

​
What is coupon reversal?

Coupon reversal allows you to undo a coupon redemption and return the rewards back to the system. This is useful when:
  • A customer needs to cancel an order that used a coupon
  • A coupon was redeemed by mistake
  • You need to correct an erroneous redemption
When a coupon is reversed, the system:
  1. Removes the rewards from the customer’s wallet
  2. Creates reversal transactions for audit purposes
  3. Updates the coupon redemption status to REVERSED
  4. Creates a REVERSED_COUPON event
  5. Recalculates the customer’s tier if necessary
const payload = {
  customer_id: "unique-customer-id",
  code: "coupon-code"
};

const response = await fetch(
  "https://app.masivo.ai/api/storefront/v1/coupons/reverse",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
    body: JSON.stringify(payload)
  }
);

​
Response

The response returns the updated wallet after reversing the coupon, with the rewards removed from wallet.totals. The redemptions array contains the lines that were reversed (negative amounts). 
{
  "data": {
    "customer_id": "unique-customer-id",
    "wallet": {
      "totals": {
        "reward-id-1": 450,
        "reward-id-2": 0
      }
    },
    "accumulations": [],
    "redemptions": [
      {
        "reward_id": "reward-id-1",
        "amount": -50,
        "issued_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

​
What happens when you try to reverse a coupon that was already reversed?

If you attempt to reverse a coupon that has already been reversed, the system will return an error: 
{
  "error": "Internal validation failed",
  "details": "This coupon redemption has already been reversed"
}

​
What happens when the rewards have already been spent?

If the customer has already used (spent or redeemed) the rewards obtained from the coupon, the reversal will fail with an error: 
{
  "error": "Internal validation failed",
  "details": "Rewards have already been spent or redeemed and cannot be reversed"
}
This validation ensures that you cannot reverse a coupon if the customer has already used those rewards in a transaction.

​
What happens when the rewards are currently reserved?

If the rewards from the coupon are currently reserved for a pending order or transaction, the reversal will fail with an error: 
{
  "error": "Internal validation failed",
  "details": "Rewards are currently reserved and cannot be reversed"
}
Rewards are considered “reserved” when they are being held for a transaction that has not yet been completed or fulfilled. This happens when:
  • A customer has an unfulfilled order that is using the rewards
  • The rewards are in a reservation state waiting for order confirmation
  • A pending transaction is holding the rewards
To reverse a coupon with reserved rewards, you must first:
  1. Cancel or complete the pending transaction using the reserved rewards
  2. Wait for the reservation to expire (if applicable)
  3. Then attempt the coupon reversal again

​
What happens when the coupon redemption is not found?

If the coupon redemption does not exist for the specified customer and code, the system will return: 
{
  "error": "Resource not found",
  "details": "Coupon redemption not found"
}

​
Important considerations

  • ⚠️ Only active redemptions can be reversed: You cannot reverse a coupon that has already been reversed
  • ⚠️ Rewards must not be spent: The customer must have the full amount of rewards in their wallet
  • ⚠️ Rewards must not be reserved: If rewards are being held for a pending transaction, they cannot be reversed
  • ⚠️ Time-sensitive operation: It’s recommended to reverse coupons as soon as possible after redemption
  • ⚠️ Audit trail: All reversals create REVERSAL transactions and a REVERSED_COUPON event for tracking
  • ⚠️ Check order status first: Before reversing a coupon, ensure no pending orders are using the rewards

​
Use cases

1. Order Cancellation 
// Customer cancels an order that used a coupon
const reverseResponse = await reverseCoupon({
  customer_id: "customer-123",
  code: "SUMMER2024"
});
2. Mistaken Redemption 
// Customer accidentally redeemed wrong coupon
const reverseResponse = await reverseCoupon({
  customer_id: "customer-456",
  code: "WRONGCODE"
});
3. Fraud Prevention 
// Detected fraudulent redemption
const reverseResponse = await reverseCoupon({
  customer_id: "suspicious-customer",
  code: "FRAUD123"
});

​
Reversal workflow

​
Events created

When a coupon is reversed, a REVERSED_COUPON event is automatically created with the following data: 
{
  "type": "REVERSED_COUPON",
  "data": {
    "customer_id": "unique-customer-id",
    "brand_id": "unique-brand-id",
    "code": "coupon-code",
    "campaign_id": "campaign-uuid"
  }
}
This event can be used for:
  • Analytics and reporting
  • Integration with external systems
  • Triggering marketing automation workflows
  • Audit and compliance purposes
⌘I