Overview

The promotions platform credits loyalty points to users when they complete transactions or other qualifying events. Users then redeem those points for eligible purchases.

In cases where an order is returned or canceled, two problems can occur:

• Reward leakage: The user keeps points they earned from a purchase they returned.
• Unfair forfeiture: The user loses points they spent on a purchase that was later canceled.

The Points Refund Management feature solves both these problems. It introduces a Reverse/Refund Points API that your system calls when a return occurs. Using this API, you can:

• Reverse earned points that are still in the promised points bucket.
• Reverse earned points from the active bucket (if the user has sufficient balance).
• Refund points the user redeemed in the returned transaction.

This document explains how the API works and how to integrate it.

Points Buckets

Before you integrate this API, understand the two-point buckets CleverTap uses:

Prerequisites

Before you use this API, make sure you have the following:

• A CleverTap account with the Promotions feature enabled.
• API credentials (Account ID and Passcode) from your CleverTap dashboard.
• The original wallet transaction ID (txnId) for the transaction you want to reverse or refund. CleverTap records this ID when points are credited or debited. You must store it on your side at the time of the original transaction.
• The user's identity value, which can be their identity string, email address, or phone number.

How API Processing Works?

When CleverTap receives a Reverse/Refund Points API call, it performs the following steps:

1. Validates the txnId: CleverTap checks that the transaction ID exists in the points ledger against a credit, promised points, or debit transaction type. If the ID is not found, the API returns an error.

2. Resolves reward records: CleverTap identifies all credit ledger entries (earned points) and debit ledger entries (redeemed points) linked to the original transaction ID.

3. Checks idempotency: If a reversal or refund has already been fully processed against this transaction ID (that is, points_balance = 0), the API returns an error to prevent duplicate processing.

4. Determines the action based on the following transaction type:

   • Promised points bucket: If earned points exist in the promised points bucket and points_balance > 0, CleverTap posts a points_reversal ledger entry with type = REVERSE. The scheduled cron job that moves these points to the active bucket is canceled.
   • Active bucket points: If earned points exist in the active bucket and points_balance > 0, CleverTap posts a points_reversal ledger entry with type = REVERSE and reduces the active wallet balance.
   • Redeemed (debited) points: If the user redeemed points in the original transaction and points_balance > 0, CleverTap posts a refund ledger entry with type = REFUND and credits the points back to the user's active wallet.

5. Updates the ledger balance: CleverTap updates the points_balance field in the original ledger record using the following formula:

   updated_points_balance = current_points_balance - reversed_points

   The original transaction record is always retained for audit purposes.

6. Calculates the new active balance: After every reversal or refund, the user's active points balance is recalculated as:

   Active points = (points_credited + points_refunded) - (points_debited + points_removed + points_expired + points_reversed)

Example Scenario: Full Transaction Reversal and Refund

Consider a scenario where a user earns 120 points from an order, redeems 50 points on the same order, and then returns the order.

In this scenario, call the Reverse/Refund Points API twice, once for the credit transaction and once for the debit transaction.

Step 1. Identify the original wallet transaction IDs (txnId) for the credit and debit entries. Your system should have stored these when the original transaction was processed.

Step 2. Call the Reverse/Refund Points API for the credit transaction:

POST https://in1.api.clevertap.com/1/promo/wallet/adjust?identity=user_01234

{
  "txnId": "wlt_credit_001",
  "description": "CUSTOMER_RETURN"
}

Step 3. Call the Reverse/Refund Points API for the debit transaction:

POST https://in1.api.clevertap.com/1/promo/wallet/adjust?identity=user_01234

{
  "txnId": "wlt_debit_002",
  "description": "CUSTOMER_RETURN"
}

Base URL

Here is an example base URL from the account in the India region to reverse or refund points for a user:

POST https://in1.api.clevertap.com/1/promo/wallet/adjust

Region

To identify the API endpoint for your account region, refer to Region.

HTTP Method

POST

Headers

For more information about the API headers used while processing API requests, refer to Headers.

Sample Request

The following is an example request to the Reverse/Refund Points API, including the required headers for authentication:

curl -X POST "https://in1.api.clevertap.com/1/promo/wallet/adjust?identity=user_01234" \
  -H "X-CleverTap-Account-Id: YOUR_ACCOUNT_ID" \
  -H "X-CleverTap-Passcode: YOUR_PASSCODE" \
  -H "Content-Type: application/json" \

Find CleverTap Account ID and Passcode

You can find the CleverTap Account ID and Passcode from the CleverTap dashboard by navigating to the Settings > Project page on the CleverTap dashboard.

Query Parameters

Body Parameters

Sample Request Payload

The following is the request payload for Reverse/Refund Points:

{
    "txnId": "YOUR_ORIGINAL_WALLET_TXN_ID",
    "points": 50,
    "description": "CUSTOMER_RETURN",
    "metadata": {
      "store_id": "store_099",
      "reason": "damaged_item"
    }
  }'

Sample Response Payload

The following are the sample response payloads for a points reversal and refund request:

{
  "status": "success",
  "records": [
    {
      "type": "reverse",
      "pointsAdjusted": 100,
      "availablePoints": 120,
      "pointsBalance": 20,
      "originalPoints": 120,
      "txnId": "led_001",
      "parentTxnId": "wlt24",
      "saleChannel": "POS",
      "orderId": "1234",
      "locationId": "abc",
      "saleAmount": 1200,
      "metadata": {
        "Key1": "value1",
        "key2": "value2"
      }
    }
  ]
}

{
  "status": "success",
  "records": [
    {
      "type": "refund",
      "pointsAdjusted": 100,
      "availablePoints": 120,
      "pointsBalance": 20,
      "originalPoints": 120,
      "txnId": "led_001",
      "parentTxnId": "wlt24",
      "saleChannel": "POS",
      "orderId": "1234",
      "locationId": "abc",
      "saleAmount": 1200,
      "metadata": {
        "Key1": "value1",
        "key2": "value2"
      }
    }
  ]
}

Response Fields

The table below provides a detailed breakdown of the response payload for the Points Reverse/Refund API:

How to Find a Wallet Transaction ID

You need the original wallet transaction ID (txnId) to call this API. Use one of the following methods to locate it:

• Method 1 — GET Wallet Transaction API: Use the GET wallet transaction API with or without filters to find the right wallet transaction ID.
• Method 2 — CleverTap Dashboard: Search for the points transaction directly in the CleverTap dashboard.
• Method 3 — Points Transaction Report: Use the CleverTap points transaction report to identify the correct transaction.

Supported API Scenarios

The following table outlines the scenarios this API supports:

Common Impact for All Scenarios

The following applies to every reverse and refund activity:

• Every reverse activity is linked to its parent credit or reverse transaction ID via the parentTxnId field.
• Every refund activity is linked to its parent debit transaction ID via the parentTxnId field.

API Behavior

The following table describes how the API handles specific cases:

Error Response

CleverTap returns HTTP 200 for all business logic errors with "status": "fail" and a custom error code of 777 in the response body.

The following is a sample error response:

{
  "status": "fail",
  "error": "No active points available for adjustment.",
  "code": 777
}

The following table lists the error cases and their corresponding messages:

Best Practices

Follow these best practices to get the most out of the Points Refund Management feature:

• Store wallet transaction IDs at the time of the original transaction. The API requires the original txnId to process any reversal or refund. If you do not store this value, you cannot call the API.
• Set your pending lock period to match your return policy window. If your return window is 30 days, configure the pending period to be at least 30 days. This ensures that earned points remain in the promised points bucket when a return is filed.
• Use the description field for auditing. Pass a meaningful value such as CUSTOMER_RETURN or a reason code. This value is stored in the ledger and appears in transaction reports.
• Use the metadata field for additional context. Pass store IDs, agent IDs, or return reference numbers to improve traceability.
• Handle idempotency on your side. Before calling the API, verify that you have not already submitted a reversal or refund for the same txnId. The API returns an error if points_balance for that transaction is already 0.
• Do not rely on this API to handle negative balances. The API does not allow wallets to go below zero. Design your return workflows accordingly.

FAQs

Can I reverse only part of the points from a transaction?

Yes. Pass the points field in the request payload with the specific number of points you want to reverse or refund. The API processes only the points you specify and leaves the remaining balance available for future adjustments.

Can I call the API multiple times against the same transaction?

Yes. As long as points_balance > 0 for the original transaction, the API accepts multiple partial reversal or refund requests. Each request creates a separate reverse or refund ledger entry linked to the original transaction.

What happens to the original transaction record in the ledger?

The original transaction record is always retained. CleverTap creates new reverse or refund entries linked to the parent record. The points_balance field in the original record is updated to reflect the remaining balance.

Does this API affect the user's loyalty tier?

Currently, tier re-evaluation triggered by a return is out of scope. However, if your tier criteria are based on points collected, the points collected value in the tier table is updated when points are reversed from the credit bucket.

Is this API available for coupon or voucher reversals?

No. Currently, the API supports wallet points only.

What region should I use for the API endpoint?

The example endpoint uses in1.api.clevertap.com. Replace in1 with the region identifier for your CleverTap account. For more information, refer to Region.