Reports

The ledger, liability and settlement.

Part of the API reference, version 2026-10. Every address below starts with the base address:

https://app.matrixrewards.co.uk/api/2026-10

Every points movement on this account, newest first

GET /ledger — the full address is https://app.matrixrewards.co.uk/api/2026-10/ledger.

Needs: the read_reports permission (in the app: “The ledger, what you owe, and settlement between stores”).

The ledger is append-only: a correction is a later row, never an edit to an earlier one.

Parameters

The answer

A page of ledger entries.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

curl "https://app.matrixrewards.co.uk/api/2026-10/ledger" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "data": [
    {
      "id": 3,
      "at": "2026-09-16T10:00:00.000Z",
      "store_key": "example-store",
      "store_name": "Example Store",
      "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
      "delta_points": 500,
      "reason": "Reward removed — points returned",
      "rule_id": "redeem_void",
      "source_type": "redeem_void",
      "source_ref": null,
      "order_ref": null,
      "code_ending": "4TPB",
      "code_ref": "5f0c2d8e91a47b36c0de"
    },
    {
      "id": 2,
      "at": "2026-09-16T10:00:00.000Z",
      "store_key": "example-store",
      "store_name": "Example Store",
      "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
      "delta_points": 50,
      "reason": "Sorry about the late parcel",
      "rule_id": "admin_adjustment",
      "source_type": "admin_adjustment",
      "source_ref": "admin|api.Kx7Qp2Lm9Vt4Rz8N|goodwill-2026-09-16-0001|mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18|50",
      "order_ref": null,
      "code_ending": null,
      "code_ref": null
    },
    {
      "id": 1,
      "at": "2026-08-04T11:02:00Z",
      "store_key": "example-store",
      "store_name": "Example Store",
      "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
      "delta_points": 640,
      "reason": "Points earned on your order",
      "rule_id": "base_earn",
      "source_type": "order",
      "source_ref": "o-1001",
      "order_ref": null,
      "code_ending": null,
      "code_ref": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Other answers

What this account owes its shoppers

GET /reports/liability — the full address is https://app.matrixrewards.co.uk/api/2026-10/reports/liability.

Needs: the read_reports permission (in the app: “The ledger, what you owe, and settlement between stores”).

Summed from the ledger, not from the balance cache. The money value is null with a reason rather than a guess when the stores redeem at different rates or none is configured.

The answer

The liability report.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

curl "https://app.matrixrewards.co.uk/api/2026-10/reports/liability" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "as_at": "2026-09-16T10:00:00Z",
  "redeemable_points": 1190,
  "net_points": 1190,
  "members_in_credit": 1,
  "total_members": 1,
  "points_expiring_within_days": 0,
  "expiring_within_days": 90,
  "outstanding_codes": [],
  "valuation": {
    "currency": "GBP",
    "minor_units": 1190,
    "major_units": "11.90"
  },
  "valuation_unavailable": null,
  "redeem_rate_by_store": [
    {
      "store_key": "example-outlet",
      "currency": "GBP",
      "redeem_points_per_major_unit": 100
    },
    {
      "store_key": "example-store",
      "currency": "GBP",
      "redeem_points_per_major_unit": 100
    }
  ]
}

Other answers

Points earned at one store and spent at another, inside a window

GET /reports/settlement — the full address is https://app.matrixrewards.co.uk/api/2026-10/reports/settlement.

Needs: the read_reports permission (in the app: “The ledger, what you owe, and settlement between stores”).

The window is two absolute UTC instants. The report keeps the engine's own field names.

Parameters

The answer

The settlement report.

An open object has no fixed set of fields: it is sent as the platform holds it, in its own field names.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

curl "https://app.matrixrewards.co.uk/api/2026-10/reports/settlement?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "report": {
    "accountId": "acc_example",
    "window": {
      "from": "2026-09-01T00:00:00Z",
      "to": "2026-09-16T00:00:00Z"
    },
    "lines": [],
    "totals": {
      "redeemedPoints": 0,
      "consumedPoints": 0,
      "attributedPoints": 0,
      "unattributedPoints": 0,
      "valueByCurrency": {}
    },
    "attributionComplete": true,
    "anomalies": [],
    "unpricedSpendSites": [],
    "unknownSpendSites": [],
    "clampedFutureRows": 0,
    "ledgerDigest": "17b799bbaf2815941767da47eebbc881fac4e92211c327b92723cad37f5003b7"
  }
}

Other answers