Members

Shoppers holding points, and the codes they hold.

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

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

Shoppers on this account

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

Needs: the read_members permission (in the app: “Members, their points, their email addresses and the last four characters of their reward codes”). A key with write_members can call it too.

Recorded in the audit log as a disclosure, counted in shoppers.

Parameters

Name	In	Required	Type	What it is
`q`	query	no	string, up to 120 characters	Email, member key or store customer reference. At most 120 characters.
`store`	query	no	string	Only members with a customer record at this store.
`sort`	query	no	one of `member_key`, `balance`, `enrolled_at`, `last_activity_at`	—
`order`	query	no	one of `asc`, `desc`	—
`limit`	query	no	integer, from 1 to 100, default `25`	1 to 100. Larger values are capped.
`cursor`	query	no	string	Opaque. Pass back `next_cursor` from the previous page, with the same filters, and on `GET /members` the same `sort` and `order`.

The answer

A page of members.

Field	Type	Always there	What it is
`data`	list of object (`MemberSummary`)	yes	—
`data[].member_key`	string	yes	—
`data[].email`	string	yes	—
`data[].balance_points`	integer	yes	The maintained balance, which the engine recomputes from the ledger under a lock on every write. `GET /members/{member_key}` sums the ledger rows there and then; the two agree unless something is wrong, and that is the only difference between them.
`data[].enrolled_at`	string	yes	—
`data[].last_activity_at`	string	yes	—
`has_more`	boolean	yes	—
`next_cursor`	string, or null	yes	—

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/members" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "data": [
    {
      "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
      "email": "alex@example.com",
      "balance_points": 640,
      "enrolled_at": "2026-08-04T11:02:00Z",
      "last_activity_at": "2026-08-04T11:02:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Status	What it means	Error pages
400	`invalid_request`: a parameter could not be read; `param` names it. `invalid_cursor`: the `cursor` is not one this list issued.	invalid_request, invalid_cursor
401	`unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer.	unauthenticated
403	`forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which.	forbidden_scope
429	`rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait.	rate_limited
503	`access_not_recorded`: the read could not be written to the account's audit log, so no data was returned.	access_not_recorded

One shopper's record

GET /members/{member_key} — the full address is https://app.matrixrewards.co.uk/api/2026-10/members/{member_key}.

Email is the only contact detail returned. The birthday a merchant's own staff screen can show is never returned here.

Parameters

Name	In	Required	Type	What it is
`member_key`	path	yes	string	—

The answer

The member.

Field	Type	Always there	What it is
`member_key`	string	yes	—
`email`	string	yes	The only contact detail this API returns.
`balance_points`	integer	yes	Summed from the ledger, not read from the balance cache.
`enrolled_at`	string	yes	—
`last_activity_at`	string	yes	—
`points_expire_at`	string, or null	yes	Null when expiry is off, which is the default.
`stores`	list of object	yes	—
`stores[].store_key`	string	yes	—
`stores[].customer_ref`	string	yes	The merchant's own customer identifier at that store.
`stores[].linked_at`	string	yes	—
`points_by_store`	list of object	yes	—
`points_by_store[].store_key`	string	yes	—
`points_by_store[].store_name`	string, or null	yes	—
`points_by_store[].earned_points`	integer	yes	Points the shopper got at this store: orders, bonuses and credits from staff.
`points_by_store[].spent_points`	integer	yes	Points exchanged for a reward at this store. Only redemptions: refunds, expiry and staff removals are in other_points.
`points_by_store[].other_points`	integer	yes	Signed. Every other movement at this store: points taken back on a refund, expired, removed by staff, returned when a reward was cancelled, or carried over when another of the shopper's store records was deleted. earned_points - spent_points + other_points is this store's net.
`outstanding_codes`	integer	yes	—
`history_url`	string	yes	—

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

Example

export MEMBER='<member_key from GET /members>'
curl "https://app.matrixrewards.co.uk/api/2026-10/members/$MEMBER" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
  "email": "alex@example.com",
  "balance_points": 640,
  "enrolled_at": "2026-08-04T11:02:00Z",
  "last_activity_at": "2026-08-04T11:02:00Z",
  "points_expire_at": null,
  "stores": [
    {
      "store_key": "example-store",
      "customer_ref": "gid://shopify/Customer/7001",
      "linked_at": "2026-08-04T11:02:00Z"
    }
  ],
  "points_by_store": [
    {
      "store_key": "example-store",
      "store_name": "Example Store",
      "earned_points": 640,
      "spent_points": 0,
      "other_points": 0
    }
  ],
  "outstanding_codes": 1,
  "history_url": "/api/2026-10/ledger?member_key=mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18"
}

Status	What it means	Error pages
401	`unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer.	unauthenticated
403	`forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which.	forbidden_scope
404	`not_found`: no such resource on this account — indistinguishable from one that does not exist at all.	not_found
429	`rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait.	rate_limited
503	`access_not_recorded`: the read could not be written to the account's audit log, so no data was returned.	access_not_recorded

The reward codes this shopper holds

GET /members/{member_key}/codes — the full address is https://app.matrixrewards.co.uk/api/2026-10/members/{member_key}/codes.

Paged: a shopper who has redeemed for two years has a history, so this list is keyset-paged like the others. Each code is named by its last four characters and its ref, never whole — and so is the cursor, which is opaque but not secret.

Parameters

Name	In	Required	Type	What it is
`member_key`	path	yes	string	—
`status`	query	no	string	'minted' is issued and unspent.
`limit`	query	no	integer, from 1 to 100, default `25`	1 to 100. Larger values are capped.
`cursor`	query	no	string	Opaque. Pass back `next_cursor` from the previous page, with the same filters, and on `GET /members` the same `sort` and `order`.

The answer

The codes.

Field	Type	Always there	What it is
`data`	list of object	yes	—
`data[].code_ending`	string, or null	yes	The last four characters of the code: enough to match what the shopper reads out. Null when the code's final run of letters and digits is shorter than twelve, as a code your own connector recorded in a short or prefixed format can be, because its last four would be all of its random part; name it by `ref`. The whole code is never returned by this API — an unused code is a live discount, and API answers end up in logs and assistant transcripts.
`data[].ref`	string, matching `^[0-9a-f]{20}$`	yes	The code's reference: what `cancelMemberCode` takes. It is derived from the redemption, never from the code, so it says nothing about the code.
`data[].store_key`	string	yes	—
`data[].reward_id`	string	yes	The reward the code was bought with, as `listRewards` gives its id; `@any-amount` for a code the shopper bought by choosing how many points to spend (`spend_any_amount`). A merchant's reward id never starts with `@`.
`data[].cost_points`	integer	yes	—
`data[].status`	string	yes	—
`data[].issued_at`	string	yes	—
`has_more`	boolean	yes	—
`next_cursor`	string, or null	yes	—

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

Example

export MEMBER='<member_key from GET /members>'
curl "https://app.matrixrewards.co.uk/api/2026-10/members/$MEMBER/codes" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "data": [
    {
      "code_ending": "4TPB",
      "ref": "5f0c2d8e91a47b36c0de",
      "store_key": "example-store",
      "reward_id": "reward_5",
      "cost_points": 500,
      "status": "minted",
      "issued_at": "2026-09-10T16:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Status	What it means	Error pages
400	`invalid_cursor`: the `cursor` is not one this list issued.	invalid_cursor
401	`unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer.	unauthenticated
403	`forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which.	forbidden_scope
404	`not_found`: no such resource on this account — indistinguishable from one that does not exist at all.	not_found
429	`rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait.	rate_limited
503	`access_not_recorded`: the read could not be written to the account's audit log, so no data was returned.	access_not_recorded

Add points to a member's balance, or take them away

POST /members/{member_key}/adjustments — the full address is https://app.matrixrewards.co.uk/api/2026-10/members/{member_key}/adjustments.

Needs: the write_members permission (in the app: “Change members’ points and cancel reward codes. This also reads members, their email addresses and the last four characters of their reward codes. Every change is logged”).

Booked to the member's earliest-linked store on this account, with the reason on the shopper's statement. At most 100,000 points either way per change, and per account at most 100,000 points added and 100,000 taken away by points changes through the API in any rolling 24 hours, across all its keys (a cancelled code's points are not counted). A test key can preview and is refused the change (403 test_mode_key). Written to the audit log in the same transaction as the change: if the entry cannot be written, the change is not made.

Parameters

Name	In	Required	Type	What it is
`member_key`	path	yes	string	—
`Idempotency-Key`	header	yes	string, matching `^[A-Za-z0-9._:-]{1,100}$`	Required on both writes, a points change and a cancel. Pick a new one for each new change and send the same one to retry it. For 24 hours from its first use, a key has three answers: the same request again gets the first answer back, byte for byte, with `Idempotency-Replayed: true`; a different request under the key is 422 `idempotency_key_reused`; and while the first request is still running, 409 `idempotency_key_in_use` with `Retry-After`. A 5xx does not use the key up: retry with the same one. For a points change the key is also the adjustment's id in the ledger, so the same change is never booked twice, whichever of the account's keys sends it, and even after the 24 hours.
`dry_run`	query	no	boolean	`true` previews the change: every check the real call makes runs, the answer has the status the real call would have, and nothing changes — except one `dry_run` entry in the audit log, because a preview shows the member's balance. When the change would happen, the preview carries a `confirmation` for exactly this request. It is the only query parameter a write takes: any other, a misspelling such as `dryRun` included, is refused with 400 `invalid_request` naming it in `param`, and nothing changes.
`Matrix-Confirmation`	header	no	string, up to 1,024 characters	The `confirmation.token` a dry run of this exact request returned. Required for keys tagged for an assistant, except on a replay: a request whose first answer is still kept, or a points change that is already made; checked whenever it is sent. It covers one request — the same key, member, body and Idempotency-Key — for 10 minutes. It proves the change was previewed first; it cannot prove a person saw the preview.

Request body

Sent as application/json.

Field	Type	Required	What it is
`delta_points`	integer, from -100,000 to 100,000, not 0	yes	Points to add (positive) or take away (negative). Not zero; at most 100,000 either way.
`reason`	string, up to 200 characters, at least 1 character	yes	Why. Shown to the shopper on their statement, and kept in the audit log.

The answer

The change, or with dry_run=true the preview of it.

One shape: AdjustmentResult.

Field	Type	Always there	What it is
`object`	always `adjustment`	yes	—
`member_key`	string	yes	—
`delta_points`	integer	yes	—
`balance_points`	integer	yes	The member's balance afterwards.
`store_key`	string	yes	The store the change is booked to: the member's earliest-linked store on this account.
`replayed`	boolean	yes	True when the ledger already held this change (the same Idempotency-Key, member and amount) and nothing new was booked.
`idempotency_key`	string	yes	—
`audit_id`	string	yes	The audit-log entry this answer rests on.

One shape: AdjustmentPreview.

Field	Type	Always there	What it is
`object`	always `adjustment_preview`	yes	—
`dry_run`	always `true`	yes	—
`outcome`	one of `would_apply`, `would_replay`	yes	—
`member_key`	string	yes	—
`delta_points`	integer	yes	—
`balance_points_before`	integer	yes	—
`balance_points_after`	integer	yes	What the real call would report. Equal to before when it would replay.
`store_key`	string	yes	—
`limit`	object, or null	yes	The account's rolling 24-hour limit in this change's direction, before it. Null when the change would be a replay (a replay spends nothing).
`limit.direction`	one of `credit`, `debit`	yes	—
`limit.limit_points`	integer	yes	—
`limit.used_points`	integer	yes	—
`limit.remaining_points`	integer	yes	—
`confirmation`	object (`Confirmation`), or null	yes	Send `token` back in `Matrix-Confirmation` with the same request (without dry_run). Null when nothing would change, or when the change would be a replay: a replay needs no confirmation, so send the request without one.
`confirmation.token`	string	yes	—
`confirmation.expires_at`	string	yes	—
`audit_id`	string	yes	The preview's own audit-log entry.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; and, when it applies, Idempotency-Replayed. What each header means.

Example

export MEMBER='<member_key from GET /members>'
curl -X POST "https://app.matrixrewards.co.uk/api/2026-10/members/$MEMBER/adjustments" \
  -H "Authorization: Bearer $MATRIX_API_KEY" \
  -H "Idempotency-Key: goodwill-2026-09-16-0001" \
  -H "Content-Type: application/json" \
  -d '{"delta_points": 50, "reason": "Sorry about the late parcel"}'

The change, made:

{
  "object": "adjustment",
  "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
  "delta_points": 50,
  "balance_points": 690,
  "store_key": "example-store",
  "replayed": false,
  "idempotency_key": "goodwill-2026-09-16-0001",
  "audit_id": "0d1e2f30-4a5b-4c6d-8e7f-00000000000d"
}

The same request with ?dry_run=true: nothing changes:

{
  "object": "adjustment_preview",
  "dry_run": true,
  "outcome": "would_apply",
  "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
  "delta_points": 50,
  "balance_points_before": 640,
  "balance_points_after": 690,
  "store_key": "example-store",
  "limit": {
    "direction": "credit",
    "limit_points": 100000,
    "used_points": 0,
    "remaining_points": 100000
  },
  "confirmation": {
    "token": "mct_EXAMPLE.EXAMPLE",
    "expires_at": "2026-09-16T10:10:00.000Z"
  },
  "audit_id": "0d1e2f30-4a5b-4c6d-8e7f-00000000000b"
}

Status	What it means	Error pages
400	`invalid_request`: a parameter or the body could not be read; `param` names it.	invalid_request
401	`unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer.	unauthenticated
403	`forbidden_scope`: the key does not hold `write_members` (`required_scope` says so). `test_mode_key`: a test key can preview a change and never make one.	forbidden_scope, test_mode_key
404	`not_found`: no such member on this account, or (cancelling a code) the member holds no code with that `ref`.	not_found
409	`idempotency_key_in_use`: a request with this key is still running (`Retry-After`). `credit_limit_reached`: the account has moved 100,000 points through the API in this direction in the last 24 hours (`direction`, `limit_points`, `used_points`). `member_has_no_store`: the member is linked to no store to book the change to.	idempotency_key_in_use, credit_limit_reached, member_has_no_store
413	`payload_too_large`: the body is over 4,096 bytes.	payload_too_large
422	`idempotency_key_reused`: this Idempotency-Key was used for a different request in the last 24 hours.	idempotency_key_reused
428	`confirmation_required`: this key is tagged for an assistant; preview with `dry_run=true` and send the returned confirmation. `confirmation_invalid`: the confirmation is not for this request, has expired, or is not one we issued (`reason`).	confirmation_required, confirmation_invalid
429	`rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait.	rate_limited
503	`change_not_recorded` (or `access_not_recorded` for a preview or a replay): the audit log could not be written, so nothing was changed or returned. Retry with the same Idempotency-Key.	change_not_recorded, access_not_recorded

Cancel a reward code and give the member back its points

POST /members/{member_key}/codes/void — the full address is https://app.matrixrewards.co.uk/api/2026-10/members/{member_key}/codes/void.

Switches the code off at the store it belongs to and credits its cost back — never one without the other. Name the code by its ref from listMemberCodes; the code itself is never sent or returned. The attempt is written to the audit log before Shopify is asked. A preview (dry_run=true) never contacts Shopify, so a store problem shows only on the real call. A cancel is not counted against the daily points limits on adjustMemberPoints: it gives back points the shopper already spent on the code.

Parameters

Name	In	Required	Type	What it is
`member_key`	path	yes	string	—
`Idempotency-Key`	header	yes	string, matching `^[A-Za-z0-9._:-]{1,100}$`	Required on both writes, a points change and a cancel. Pick a new one for each new change and send the same one to retry it. For 24 hours from its first use, a key has three answers: the same request again gets the first answer back, byte for byte, with `Idempotency-Replayed: true`; a different request under the key is 422 `idempotency_key_reused`; and while the first request is still running, 409 `idempotency_key_in_use` with `Retry-After`. A 5xx does not use the key up: retry with the same one. For a points change the key is also the adjustment's id in the ledger, so the same change is never booked twice, whichever of the account's keys sends it, and even after the 24 hours.
`dry_run`	query	no	boolean	`true` previews the change: every check the real call makes runs, the answer has the status the real call would have, and nothing changes — except one `dry_run` entry in the audit log, because a preview shows the member's balance. When the change would happen, the preview carries a `confirmation` for exactly this request. It is the only query parameter a write takes: any other, a misspelling such as `dryRun` included, is refused with 400 `invalid_request` naming it in `param`, and nothing changes.
`Matrix-Confirmation`	header	no	string, up to 1,024 characters	The `confirmation.token` a dry run of this exact request returned. Required for keys tagged for an assistant, except on a replay: a request whose first answer is still kept, or a points change that is already made; checked whenever it is sent. It covers one request — the same key, member, body and Idempotency-Key — for 10 minutes. It proves the change was previewed first; it cannot prove a person saw the preview.

Request body

Sent as application/json.

Field	Type	Required	What it is
`ref`	string, matching `^[0-9a-f]{20}$`	yes	The code's `ref`, from `listMemberCodes`. The code itself is never sent: a write request's body passes through logs and assistant transcripts, and a live code is spendable.

The answer

The change, or with dry_run=true the preview of it.

One shape: VoidResult.

Field	Type	Always there	What it is
`object`	always `code_void`	yes	—
`result`	one of `voided`, `already_voided`, `nothing_to_void`	yes	`voided`: switched off at Shopify and the points given back. `already_voided`: done before, not again. `nothing_to_void`: the code never held points to give back.
`member_key`	string	yes	—
`code_ending`	string, or null	yes	The last four characters of the code, or null for a code too short to show any of (see CodePage). The code itself is never returned.
`store_key`	string, or null	yes	—
`balance_points`	integer	yes	—
`audit_id`	string	yes	The audit-log entry written before Shopify was asked.

One shape: VoidPreview.

Field	Type	Always there	What it is
`object`	always `code_void_preview`	yes	—
`dry_run`	always `true`	yes	—
`outcome`	one of `would_void`, `already_voided`, `nothing_to_void`, `would_replay`	yes	—
`member_key`	string	yes	—
`code_ending`	string, or null	yes	—
`store_key`	string, or null	yes	—
`cost_points`	integer, or null	yes	What the code cost. Null when the answer would be a replay of a stored one.
`balance_points_before`	integer	yes	—
`balance_points_after`	integer	yes	—
`confirmation`	object (`Confirmation`), or null	yes	Send `token` back in `Matrix-Confirmation` with the same request (without dry_run). Null when nothing would change, or when the change would be a replay: a replay needs no confirmation, so send the request without one.
`confirmation.token`	string	yes	—
`confirmation.expires_at`	string	yes	—
`audit_id`	string	yes	—

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; and, when it applies, Idempotency-Replayed. What each header means.

Example

export MEMBER='<member_key from GET /members>'
curl -X POST "https://app.matrixrewards.co.uk/api/2026-10/members/$MEMBER/codes/void" \
  -H "Authorization: Bearer $MATRIX_API_KEY" \
  -H "Idempotency-Key: cancel-2026-09-16-0001" \
  -H "Content-Type: application/json" \
  -d '{"ref": "5f0c2d8e91a47b36c0de"}'

The change, made:

{
  "object": "code_void",
  "result": "voided",
  "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
  "code_ending": "4TPB",
  "store_key": "example-store",
  "balance_points": 1190,
  "audit_id": "0d1e2f30-4a5b-4c6d-8e7f-000000000011"
}

The same request with ?dry_run=true: nothing changes:

{
  "object": "code_void_preview",
  "dry_run": true,
  "outcome": "would_void",
  "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
  "code_ending": "4TPB",
  "store_key": "example-store",
  "cost_points": 500,
  "balance_points_before": 690,
  "balance_points_after": 1190,
  "confirmation": {
    "token": "mct_EXAMPLE.EXAMPLE",
    "expires_at": "2026-09-16T10:10:00.000Z"
  },
  "audit_id": "0d1e2f30-4a5b-4c6d-8e7f-00000000000f"
}

Members

Shoppers on this account

Parameters

The answer

Example

Other answers

One shopper's record

Parameters

The answer

Example

Other answers

The reward codes this shopper holds

Parameters

The answer

Example

Other answers

Add points to a member's balance, or take them away

Parameters

Request body

The answer

Example

Other answers

Cancel a reward code and give the member back its points

Parameters

Request body

The answer

Example

Other answers