Get group points ledger

Time	Status	User Agent
Retrieving recent requests…

Use this API to retrieve cross-member point redemption and reversal events for a user group. A user group is a set of customers who share a redeemable points wallet — members can redeem from the shared balance on behalf of the group. The caller must be an active member of a user group with cross-member redemption enabled.

The response includes a real-time group balance snapshot, per-member balances, and a paginated list of events. Use scope=user for a member's personal view (entries where they transacted or had points drawn from their wallet), or scope=group for the full group history.

📘
The v1.1 redemption API (POST /v1.1/points/redeem) draws from a single customer's individual wallet. The v2 API extended this to draw from the combined balance of all members in a user group — and this endpoint provides the per-member audit trail for those group redemption events. For general group transaction history — purchases, regular redemptions, and returns — use Get group transactions.

What this API supports

Two views controlled by scope: a personal member view (user) and a full group history (group).
Filter by event type (CROSS_MEMBER_REDEMPTION, CROSS_MEMBER_REDEMPTION_REVERSAL), date range, or a specific transactionRef.
Per-entry breakdown showing exactly which member's wallet was affected and by how much.
userRole on each entry when scope=user: TRANSACTING (caller initiated the redemption), SOURCE (caller's points were drawn by another member's transaction), or BOTH (caller both initiated and had points drawn from their own wallet).
Group balance and individual member balances at query time.

Example request

curl -X GET 'https://{host}/v2/customers/1003/crossMemberLedger?scope=user&pageNumber=1&pageSize=20' \
  -u USERNAME:{password} \
  -H 'Accept: application/json'

curl -X GET 'https://{host}/v2/customers/1003/crossMemberLedger?scope=group&startDate=2026-03-01T00:00:00Z&endDate=2026-04-01T00:00:00Z' \
  -u USERNAME:{password} \
  -H 'Accept: application/json'

API Quick Reference

GET /v2/customers/{id}/crossMemberLedger

Response
   └─ entity (object)
       ├─ groupDetails (object)
       │   ├─ groupId (number)
       │   ├─ groupBalance (number)
       │   ├─ memberCount (number)
       │   └─ members [] (array)
       │       ├─ customerId (number)
       │       └─ balance (number)
       ├─ pageDetails (object)
       │   ├─ pageNumber (number)
       │   ├─ pageSize (number)
       │   ├─ totalEntries (number)
       │   └─ pageCount (number)
       └─ entries [] (array)
           ├─ eventLogId (number)
           ├─ eventName (string)
           ├─ transactingCustomerId (number)
           ├─ transactionRef (string)
           ├─ createdDate (string)
           ├─ createdDateISO (string)
           ├─ netPointsOnEvent (string)
           ├─ status (string — only on CROSS_MEMBER_REDEMPTION rows)
           ├─ userRole (string — only when scope=user)
           ├─ redemptionId (string — only on CROSS_MEMBER_REDEMPTION entries)
           ├─ reversalId (string — only on CROSS_MEMBER_REDEMPTION_REVERSAL entries)
           ├─ transactionNumber (string)
           ├─ externalReferenceNumber (string)
           ├─ notes (string)
           ├─ redemptionPurpose (string)
           └─ entryDetails [] (array)
               ├─ customerId (number)
               ├─ points (string)
               ├─ reversedAmount (string — only on CROSS_MEMBER_REDEMPTION rows)
               ├─ expiryBatchDate (string — ISO-8601)
               ├─ status (string — only on CROSS_MEMBER_REDEMPTION rows)
               ├─ pointsAwardedId (number)
               └─ pointsAwardedType (string)

Prerequisites

Basic authentication. Credentials must be authorised for the org that owns the customer.
The org must have ENABLE_CROSS_MEMBER_REDEMPTION enabled.
The customer must be an active member of a user group.

Resource information


Pagination support	Yes (`pageNumber` / `pageSize`)
Batch support	No

Path parameters

Field	Type	Required	Description
`id`	Long	Yes	Customer ID of any active member of the target user group. The API automatically resolves the group from this customer's user group membership — you do not need to supply a group ID separately. The customer must be enrolled in a user group with cross-member redemption enabled for their org.

Query parameters

Field	Type	Required	Description
`scope`	Enum	Optional	Scope of the results. `user`: returns only entries where the customer was the transacting member or had points drawn from their wallet. `group`: returns all redemption and reversal events for the entire group. Supported values: `user`, `group`. Defaults to `user`.
`eventName`	String (CSV)	Optional	Filter by event type. Supported values: `CROSS_MEMBER_REDEMPTION` (points drawn from the group balance), `CROSS_MEMBER_REDEMPTION_REVERSAL` (full or partial reversal of a prior group redemption). Pass multiple values as a comma-separated list. Defaults to all event types.
`transactionRef`	String	Optional	Filter by transaction reference. Returns entries matching the given reference, including the original redemption and any associated reversal. Corresponds to the `externalReferenceNumber` passed at redemption time.
`startDate`	String	Optional	Start date and time for filtering events. Date and time in ISO 8601 format. Example: `2026-03-25T11:00:00+05:30`. Defaults to 30 days before the request time.
`endDate`	String	Optional	End date and time for filtering events. Date and time in ISO 8601 format. Example: `2026-04-25T11:00:00+05:30`. Must be after `startDate`. Defaults to the current time.
`pageNumber`	Integer	Optional	Page number to retrieve. To view the first page, set the value to `1`. Defaults to `1`.
`pageSize`	Integer	Optional	Number of ledger records to display per page. For example, if the total records are 15 and the limit is 5, the first page will display the first 5 records. The maximum supported limit is 100.
`sort`	String	Optional	Sort order for results. Supported values: `createdDate:desc` (newest first, default), `createdDate:asc` (oldest first).
`programId`	Integer	Optional	Filters member balances using the specified loyalty program's redeemable wallet. When set, EMF uses this program instead of the org's default program. Returns error `1005` if the `programId` is not valid for the org.

Example response

{
    "groupDetails": {
        "groupId": 3957188,
        "groupBalance": 9990,
        "memberCount": 9,
        "members": [
            {
                "customerId": 568376574,
                "balance": 0
            },
            {
                "customerId": 568376576,
                "balance": 9990
            },
            {
                "customerId": 568376577,
                "balance": 0
            },
            {
                "customerId": 568376578,
                "balance": 0
            },
            {
                "customerId": 568378418,
                "balance": 0
            },
            {
                "customerId": 568376611,
                "balance": 0
            },
            {
                "customerId": 568376575,
                "balance": 0
            },
            {
                "customerId": 568418103,
                "balance": 0
            },
            {
                "customerId": 568418155,
                "balance": 0
            }
        ]
    },
    "pageDetails": {
        "pageNumber": 1,
        "pageSize": 20,
        "totalEntries": 1,
        "pageCount": 1
    },
    "entries": [
        {
            "eventLogId": 674422903,
            "eventName": "CROSS_MEMBER_REDEMPTION",
            "transactingCustomerId": 568376576,
            "transactionRef": "28453291",
            "createdDate": "2026-06-01 11:02:33",
            "createdDateISO": "2026-06-01T11:02:33Z",
            "netPointsOnEvent": "-10.000",
            "status": "ACTIVE",
            "redemptionId": "uN1oA9",
            "transactionNumber": "txn-166",
            "notes": "",
            "redemptionPurpose": "",
            "entryDetails": [
                {
                    "customerId": 568376576,
                    "points": "-10.000",
                    "reversedAmount": "0.000",
                    "expiryBatchDate": "2026-06-01T05:32:34Z",
                    "status": "ACTIVE",
                    "pointsAwardedId": 747981377,
                    "pointsAwardedType": "POINT_AWARDED_CUSTOMER_PROMOTION"
                }
            ]
        }
    ],
    "warnings": []
}

{
  "groupDetails": {
    "groupId": 12345,
    "groupBalance": 1250.000,
    "memberCount": 4,
    "members": [
      { "customerId": 1001, "balance": 400.000 },
      { "customerId": 1002, "balance": 260.000 },
      { "customerId": 1003, "balance": 500.000 },
      { "customerId": 1004, "balance": 90.000 }
    ]
  },
  "pageDetails": { "pageNumber": 1, "pageSize": 20, "totalEntries": 1, "pageCount": 1 },
  "entries": [
    {
      "eventLogId": 999821,
      "eventName": "CROSS_MEMBER_REDEMPTION",
      "transactingCustomerId": 1003,
      "transactionRef": "TXN-882291",
      "createdDate": "2026-04-01 10:30:00",
      "createdDateISO": "2026-04-01T10:30:00Z",
      "netPointsOnEvent": "-350.000",
      "status": "PARTIALLY_REVERSED",
      "userRole": "TRANSACTING",
      "entryDetails": [
        { "customerId": 1004, "points": "-10.000",  "reversedAmount": "0.000",   "expiryBatchDate": "2026-04-02T00:00:00Z", "status": "ACTIVE" },
        { "customerId": 1001, "points": "-100.000", "reversedAmount": "0.000",   "expiryBatchDate": "2026-04-05T00:00:00Z", "status": "ACTIVE" },
        { "customerId": 1002, "points": "-240.000", "reversedAmount": "150.000", "expiryBatchDate": "2026-04-10T00:00:00Z", "status": "PARTIALLY_REVERSED" }
      ]
    }
  ],
  "warnings": []
}

Response parameters

Field	Type	Description
`groupDetails`	Object	Real-time group balance snapshot at query time.
`.groupId`	Long	Unique identifier of the group.
`.groupBalance`	Number	Sum of all active group members' current redeemable balances at query time.
`.memberCount`	Integer	Count of active group members.
`.members`	Array	Per-member balance list.
`..customerId`	Long	Customer ID of the group member.
`..balance`	Number	Current individual redeemable balance for this member.
`pageDetails`	Object	Pagination metadata for the current response.
`.pageNumber`	Integer	Current page number (1-based).
`.pageSize`	Integer	Number of entries on this page.
`.totalEntries`	Integer	Total entries across all pages. Reflects the date-range and `scope` filters but may not account for the `eventName` filter — treat it as an upper bound when filtering by event type.
`.pageCount`	Integer	Total pages: `ceil(totalEntries / pageSize)`.
`entries`	Array	Paginated list of redemption and reversal events.
`.eventLogId`	Long	Shared event log ID across all source-member rows of a single redemption.
`.eventName`	Enum	Type of event. Possible values: `CROSS_MEMBER_REDEMPTION` (points drawn from the group balance), `CROSS_MEMBER_REDEMPTION_REVERSAL` (full or partial reversal of a prior group redemption).
`.transactingCustomerId`	Long	Customer ID of the member who initiated the redemption.
`.transactionRef`	String	Transaction reference. The same value appears on the original redemption and on any reversal. Corresponds to the `externalReferenceNumber` passed at redemption time.
`.createdDate`	String	Event timestamp in `yyyy-MM-dd HH:mm:ss` format (org timezone).
`.createdDateISO`	String	Same timestamp in ISO 8601 format (UTC).
`.netPointsOnEvent`	String	Signed net change across the group for this event. Negative on redemption rows, positive on reversal rows.
`.status`	Enum	Aggregate status of the redemption. Only present on `CROSS_MEMBER_REDEMPTION` rows. Supported values: `ACTIVE`, `REVERSED`, `PARTIALLY_REVERSED`.
`.userRole`	Enum	Role of the caller in this event. Only present when `scope=user`. Supported values: `TRANSACTING` (caller initiated the redemption), `SOURCE` (caller's points were drawn but caller did not transact), `BOTH` (caller initiated and also had points drawn from their own wallet).
`.redemptionId`	String	Unique identifier of the redemption record for this event. Only present on `CROSS_MEMBER_REDEMPTION` entries; absent on reversal entries.
`.reversalId`	String	Unique identifier of the reversal record's redemption entry. Only present on `CROSS_MEMBER_REDEMPTION_REVERSAL` entries.
`.transactionNumber`	String	Bill number recorded on the redemption transaction.
`.externalReferenceNumber`	String	External reference number recorded on the redemption transaction. Typically the same value as `.transactionRef`.
`.notes`	String	Notes recorded on the redemption transaction.
`.redemptionPurpose`	String	Purpose recorded on the redemption transaction.
`.entryDetails`	Array	Per-source-member breakdown for this event.
`..customerId`	Long	Customer ID of the source member whose wallet was affected.
`..points`	String	Signed point change on this member's wallet. Negative on redemption rows, positive on reversal rows.
`..reversedAmount`	String	Cumulative points reversed from this member's contribution to date. Only present on `CROSS_MEMBER_REDEMPTION` rows.
`..expiryBatchDate`	String	Expiry date of the points batch drawn from or restored to this member. Date and time in ISO 8601 format.
`..status`	Enum	Per-row status. Only present on `CROSS_MEMBER_REDEMPTION` rows. Supported values: `ACTIVE`, `REVERSED`, `PARTIALLY_REVERSED`.
`..pointsAwardedId`	Long	Identifier of the originating points grant row from which these points were deducted. Use this to trace a deduction back to the event that awarded the points.
`..pointsAwardedType`	String	Type of the originating points grant. Possible values: `POINT_AWARDED`, `POINT_AWARDED_BILL_PROMOTION`, `POINT_AWARDED_LINEITEM`, `POINT_AWARDED_LINEITEM_PROMOTION`, `POINT_AWARDED_CUSTOMER_PROMOTION`.

Error and warning codes

Code	Type	Description
1001	Error	Invalid date format. Use ISO 8601 (e.g. `2026-03-25T11:00:00+05:30`).
1002	Error	`endDate` is before `startDate`.
1003	Error	`pageSize` is outside the allowed range (1–100), or `pageNumber` is less than 1.
1004	Error	Invalid value for `scope` (allowed: `user`, `group`) or `eventName` (allowed: `CROSS_MEMBER_REDEMPTION`, `CROSS_MEMBER_REDEMPTION_REVERSAL`).
1005	Error	Invalid `programId`. The specified program does not exist for this org.
3301	Error	The customer is not enrolled in a cross-member-eligible group.
3401	Error	The customer does not belong to this org.
5000	Error	Internal server error. Retry the request after a short delay.

Example request

API Quick Reference

Prerequisites

Resource information

Path parameters

Query parameters

Example response

Response parameters

Error and warning codes

200Successful response

400Validation error

404Customer not enrolled in a cross-member group