Overview

The Get Wallet Transactions API allows you to retrieve wallet transaction details for a specific user. You can integrate this API at relevant touchpoints within the application to display transaction details on the user interface.

This API provides the following information:

• Transaction History: Includes a comprehensive log of all wallet transactions, that is, credits, debits, and expirations processed through various sources linked to the user's wallet.
• Promised Points Transactions: Displays points yet to be credited to the user's wallet based on their activation date. This allows users to monitor points scheduled for future credit. For example, if a user earns 100 points for a transaction with a 7-day activation period, these points remain in the Pending bucket until the activation period ends. After 7 days, they move to Active status and become redeemable.
• Expiring Points: Displays points nearing expiration along with their expiry dates, helping users track and redeem them in time to avoid losing benefits.
• System Keys and Metadata: Transactions also include additional system keys such as, saleChannel, locationId, saleAmount, and orderId. A metadata object with key–value pairs is also returned, reflecting any data provided when the Debit/Credit transaction was created. If no metadata was associated, the field is returned as null.

Base URL

Here is an example base URL from the account in the India region:

https://in1.api.clevertap.com/1/promo/transactions

Region

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

Headers

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

HTTP Method

GET

Query Parameters

The API requires the following query parameters:

Sample Request

Here is an example request to the Get Wallet Transactions API, including headers needed to authenticate the request:

curl -X GET "https://in1.api.clevertap.com/1/promo/transactions?identity=krishna123&walletId=2163" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: 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.

Sample Response

The Get Wallet Transactions API response depends on query parameters, pagination settings, and transaction sources. The API returns an array of objects, with each object containing details about a specific transaction for the given walletId.

The following sample response returns the paginated list of transaction details:

{
   "status": "success",
   "record": {
       "promisedPoints": {
           "totalPromisedPoints": 0,
           "promisedPointsList": []
       },
       "pointsExpiring": {
           "earliestExpiryTimestamp": 1754471850,
           "pointsExpiringSoon": 77,
           "pointsExpiringList": [
               {
                   "expiryTimestamp": 1754471850,
                   "points": 77
               },
               {
                   "expiryTimestamp": 1754472109,
                   "points": 7.7
               }
           ]
       },
       "allTransactions": [
           {
               "txnTimestamp": 1754386499,
               "saleAmount": 0,
               "metadata": null,
               "orderId": "",
               "saleChannel": "",
               "campaignId": 1754386284,
               "locationId": "",
               "txnSource": "SYSTEM",
               "description": "Points expired automatically by system",
               "type": "EXPIRED",
               "tnxId": "wl_wB3FNMnD0ea0QD0xwfg1W",
               "points": 259.9
           },
           {
               "txnTimestamp": 1754384850,
               "saleAmount": 1000,
               "metadata": {
                   "Key1": "Test1",
                   "key2": "Test2"
               },
               "orderId": "order123",
               "saleChannel": "UPI",
               "campaignId": 0,
               "locationId": "BAN123",
               "txnSource": "API",
               "description": "Reward points for purchase",
               "type": "CREDIT",
               "tnxId": "wl_71ezcyzGWLc0S19qeCUo1",
               "points": 77
           }
       ]
   }
}

The sections below provide a detailed breakdown of the response payload for the Get Wallet Transactions API.

pointsExpiring Object

The pointsExpiring object returns details about reward points nearing expiry. It includes information such as the total points expiring soon, the earliest expiry date, and a detailed list of points with their respective expiry timestamps.

allTransactions Object

The allTransactions object returns the complete transaction history of the wallet, including credits, debits, expired, and pending transactions. Each transaction entry provides comprehensive details such as the transaction source, type, description, timestamp, and points involved.

📘

Note

• For transactions created through the Debit/Credit API, the system keys, i.e., saleChannel, locationId, saleAmount and any metadata provided will be returned in the response.
• For expired or system-generated transactions, these fields may not apply and can appear as empty strings, i.e.,"", 0, or null. For example, refer to the Sample Response.

promisedPoints Object

The promisedPoints object returns reward points that have yet to be credited to the wallet. It specifies the activation timestamp for promised points, a breakdown of individual entries, and the total promised points awaiting activation.

Errors

To know the errors applicable to the Get Wallet Transactions API, refer to API Error Cases.