Overview

The Get Wallet Transactions API helps you retrieve wallet transaction details for a specific user. You can integrate this API at relevant touchpoints within your 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: Displays points that have 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 before they expire to avoid losing benefits.
• System Keys and Metadata: Includes 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 or credit transaction was created. If no metadata was associated, the field is returned as null.

Base URL

The following is a sample base URL:

https://<region>.api.clevertap.com/1/promo/transactions

For region-specific endpoints, refer to Region.

HTTP Method

GET

Headers

For more information about API headers, refer to Headers.

Query Parameters

The following table lists the accepted query parameters:

Filter Behavior

The following rules apply when using query parameters to filter wallet transactions.

Date Range Behavior

The from and to parameters let you filter transactions to a specific time window. Both values must be passed in UTC epoch format (seconds). The following rules define how the API handles different date range inputs.

For full-day filtering, pass from as 00:00:00 UTC and to as 23:59:59 UTC for the target date, converted to epoch. For example, to filter all transactions on January 1, 2024 (UTC), pass from=1704067200&to=1704153599.

Example Request

The following is a sample request to the Get Wallet Transactions API, showing the headers needed to authenticate the request.

curl -X GET "https://<region>.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"

curl -X GET "https://<region>.api.clevertap.com/1/promo/transactions?identity=krishna123&walletId=2163&type=credit,debit&txnSource=campaign&campaignId=456&from=1704067200&to=1706745600" \
  -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 Settings > Project.

Example Response

The following is a sample response. The API returns an array of objects, with each object containing details about a specific transaction for the given walletId.

{
  "status": "success",
  "record": {
    "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
      }
    ],
    "pagination": {
      "currentPage": 1,
      "pageSize": 25,
      "totalPages": 10,
      "totalRecords": 248,
      "hasNext": true
    },
    "promisedPoints": {
      "totalPromisedPoints": 0,
      "promisedPointsList": []
    },
    "pointsExpiring": {
      "earliestExpiryTimestamp": 1754471850,
      "pointsExpiringSoon": 77,
      "pointsExpiringList": [
        {
          "expiryTimestamp": 1754471850,
          "points": 77
        },
        {
          "expiryTimestamp": 1754472109,
          "points": 7.7
        }
      ]
    }
  }
}

The sections below provide a detailed breakdown of the response payload.

allTransactions Array

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

The following table describes the fields in each allTransactions entry.

pagination Object

The pagination object is returned alongside the allTransactions array and provides details about the total volume of matching records and your current position within the paginated results. Use this object to build pagination controls in your platform's user interface, for example, displaying "Page 2 of 10" or enabling a Next Page button.

The following table describes the pagination fields.

promisedPoints Object

The promisedPoints object returns reward points that are 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.

The following table describes the promisedPoints fields.

pointsExpiring Object

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

The following table describes the pointsExpiring fields.

Errors

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