Overview

The Get Wallet Transactions API helps 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: Displays points yet to be credited to the user 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/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 your account region, 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:

📘

Note

• All filter parameters are optional. Filters not passed, or passed with blank or null values, are silently ignored.
• Filters only apply to the allTransactions object in the response. The promisedPoints and pointsExpiring objects are not affected and always return their full data.
• When no transactions match the applied filters, the allTransactions array returns empty. This is not an error.
• All filter keys work together with AND logic by default.

Filter Behavior

The following rules apply when using query parameters to filter wallet transactions. Understanding these behaviors helps you combine filters correctly and avoid unexpected results.

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.

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" 

curl -X GET "https://in1.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 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": {
    "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
        }
      ]
    }
  }
}

📘

Note

• The parameters type, txnSource, saleChannel, campaignId, orderId, and locationId in each allTransactions entry correspond directly to the optional query parameters you can use to filter results.
• The from and to query parameters filter based on the txnTimestamp field.
• The promisedPoints and pointsExpiring objects are not affected by any filters applied.

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

allTransactions Object

The allTransactionsobject 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 keys may not apply and can appear as empty strings, i.e.,"", 0, or null. For example, refer to the Sample Response.

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.

📘

Note

Pagination applies only to the allTransactions object. The promisedPoints and pointsExpiring objects always return up to 50 records each, unaffected by filters.

promisedPoints Object

The promisedPointsobject 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.

pointsExpiring Object

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

Errors

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