> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse a coupon

> Learn how to reverse a coupon redemption using Masivo's REST API

<Note>
  Check the complete list of parameters and responses of the [`POST Reverse
      coupon`](/api-reference/coupons/reverse/post) endpoint to reverse a coupon
  redemption
</Note>

### 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

```typescript theme={null}
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).

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```typescript theme={null}
// Customer cancels an order that used a coupon
const reverseResponse = await reverseCoupon({
  customer_id: "customer-123",
  code: "SUMMER2024"
});
```

**2. Mistaken Redemption**

```typescript theme={null}
// Customer accidentally redeemed wrong coupon
const reverseResponse = await reverseCoupon({
  customer_id: "customer-456",
  code: "WRONGCODE"
});
```

**3. Fraud Prevention**

```typescript theme={null}
// Detected fraudulent redemption
const reverseResponse = await reverseCoupon({
  customer_id: "suspicious-customer",
  code: "FRAUD123"
});
```

### Reversal workflow

```mermaid theme={null}
graph TD
    A[Customer requests reversal] --> B{Redemption exists?}
    B -->|No| C[Return 404 Not Found]
    B -->|Yes| D{Already reversed?}
    D -->|Yes| E[Return 422 Already Reversed]
    D -->|No| F{Rewards reserved?}
    F -->|Yes| G[Return 422 Currently Reserved]
    F -->|No| H{Rewards spent?}
    H -->|Yes| I[Return 422 Cannot Reverse]
    H -->|No| J[Remove rewards from wallet]
    J --> K[Create REVERSAL transactions]
    K --> L[Update redemption status]
    L --> M[Create REVERSED_COUPON event]
    M --> N[Return success response]
```

### Events created

When a coupon is reversed, a `REVERSED_COUPON` event is automatically created with the following data:

```json theme={null}
{
  "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