# Matrix Rewards API

> The account-scoped HTTP API for Matrix Rewards, loyalty points for Shopify stores. Version `2026-10`, base `https://app.matrixrewards.co.uk/api/2026-10`. Authenticate with an account key: `Authorization: Bearer mrk_live_...`. A points change and a code cancel each need an `Idempotency-Key` and can be previewed with `?dry_run=true`; a key tagged for an AI assistant must preview and send the preview's confirmation in `Matrix-Confirmation` before anything changes (`428` `confirmation_required` otherwise). Failures are `application/problem+json` with a `code`.

Available on the Shopify App Store.

Contract: 2026-10 sha256:35af153960028890fea5738799f5a71e535e1eea4dd3f6b8d5f50b37f02363da

## Guides

- [API](https://matrixrewards.co.uk/docs.md): What the API does today, what it does not do yet, and where to start.
- [Authentication](https://matrixrewards.co.uk/docs/authentication.md): Keys, permissions, test keys, assistant keys, rotating, revoking, and what a key never returns.
- [Safe retries and previews](https://matrixrewards.co.uk/docs/idempotency.md): Idempotency-Key and ?dry_run=true, with a worked preview and change, and how a key for an AI assistant confirms a change.

## Reference

- [OpenAPI contract, version 2026-10](https://app.matrixrewards.co.uk/api/openapi/2026-10.json): every call, field and answer, machine-readable.
- [API versions](https://matrixrewards.co.uk/docs/api.md): The versions served, each with its contract.
- [API reference 2026-10](https://matrixrewards.co.uk/docs/api/2026-10.md): Base address, authentication, conventions, and every operation.
- [Account](https://matrixrewards.co.uk/docs/api/2026-10/account.md): What this key is and what it reaches.
- [Stores](https://matrixrewards.co.uk/docs/api/2026-10/stores.md): The stores on the account and their programmes.
- [Members](https://matrixrewards.co.uk/docs/api/2026-10/members.md): Shoppers holding points, and the codes they hold.
- [Reports](https://matrixrewards.co.uk/docs/api/2026-10/reports.md): The ledger, liability and settlement.
- [Billing](https://matrixrewards.co.uk/docs/api/2026-10/billing.md): Usage against the plan, and the recorded plan.
- [Log](https://matrixrewards.co.uk/docs/api/2026-10/log.md): What every key did, and what it was shown.
- [Webhooks](https://matrixrewards.co.uk/docs/api/2026-10/webhooks.md): Where every points movement is sent, and a way to check a receiver.

## Optional

- [Errors](https://matrixrewards.co.uk/docs/errors.md): The shape of an error answer, and every code with what to do and whether to send again.
- [invalid_request](https://matrixrewards.co.uk/docs/errors/invalid_request.md): The request could not be understood
- [invalid_cursor](https://matrixrewards.co.uk/docs/errors/invalid_cursor.md): The cursor is not one this endpoint issued
- [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md): No usable API key was presented
- [forbidden_scope](https://matrixrewards.co.uk/docs/errors/forbidden_scope.md): This key does not carry the scope this call needs
- [not_found](https://matrixrewards.co.uk/docs/errors/not_found.md): No such resource
- [unsupported_version](https://matrixrewards.co.uk/docs/errors/unsupported_version.md): That API version is not served here
- [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md): Too many requests for this key
- [internal](https://matrixrewards.co.uk/docs/errors/internal.md): Something went wrong at our end
- [access_not_recorded](https://matrixrewards.co.uk/docs/errors/access_not_recorded.md): The access could not be recorded, so the data was not returned
- [payload_too_large](https://matrixrewards.co.uk/docs/errors/payload_too_large.md): The request body is larger than this endpoint accepts
- [idempotency_key_reused](https://matrixrewards.co.uk/docs/errors/idempotency_key_reused.md): This Idempotency-Key was already used for a different request
- [idempotency_key_in_use](https://matrixrewards.co.uk/docs/errors/idempotency_key_in_use.md): A request with this Idempotency-Key is still being processed
- [confirmation_required](https://matrixrewards.co.uk/docs/errors/confirmation_required.md): This key must preview the change and send back its confirmation
- [confirmation_invalid](https://matrixrewards.co.uk/docs/errors/confirmation_invalid.md): The confirmation does not match this request, or has expired
- [test_mode_key](https://matrixrewards.co.uk/docs/errors/test_mode_key.md): A test key can preview a change but never make one
- [credit_limit_reached](https://matrixrewards.co.uk/docs/errors/credit_limit_reached.md): The daily limit for points changed through the API has been reached
- [member_has_no_store](https://matrixrewards.co.uk/docs/errors/member_has_no_store.md): This member is not linked to a store the change could be booked to
- [code_already_used](https://matrixrewards.co.uk/docs/errors/code_already_used.md): The code has already been spent at checkout
- [store_not_connected](https://matrixrewards.co.uk/docs/errors/store_not_connected.md): The store this code belongs to is not connected
- [upstream_failed](https://matrixrewards.co.uk/docs/errors/upstream_failed.md): Shopify did not confirm the code was switched off, so nothing was changed
- [change_not_recorded](https://matrixrewards.co.uk/docs/errors/change_not_recorded.md): The change could not be recorded, so it was not made
- [forbidden_for_assistant](https://matrixrewards.co.uk/docs/errors/forbidden_for_assistant.md): A key for an assistant cannot manage webhooks
- [webhook_limit_reached](https://matrixrewards.co.uk/docs/errors/webhook_limit_reached.md): This account already has as many webhook endpoints as it may
- [settings_changed](https://matrixrewards.co.uk/docs/errors/settings_changed.md): The programme changed after it was read, so nothing was changed
- [retroactive_change](https://matrixrewards.co.uk/docs/errors/retroactive_change.md): The expiry change would reach back before shoppers were told
- [programme_write_limit](https://matrixrewards.co.uk/docs/errors/programme_write_limit.md): The daily limit for programme changes through the API has been reached
- [last_reward](https://matrixrewards.co.uk/docs/errors/last_reward.md): The store's only reward cannot be removed
- [offer_read_only](https://matrixrewards.co.uk/docs/errors/offer_read_only.md): This rule is not one the API changes
- [offer_ended](https://matrixrewards.co.uk/docs/errors/offer_ended.md): The campaign has ended, so it can only be removed
- [programme_not_set_up](https://matrixrewards.co.uk/docs/errors/programme_not_set_up.md): This store has no programme set up yet
- [assistant_limit](https://matrixrewards.co.uk/docs/errors/assistant_limit.md): An assistant's key cannot make a change this large
- [invalid_image](https://matrixrewards.co.uk/docs/errors/invalid_image.md): The picture is not one a store can use
- [too_many_images](https://matrixrewards.co.uk/docs/errors/too_many_images.md): The store already keeps as many pictures as it may
- [shopify_file_unavailable](https://matrixrewards.co.uk/docs/errors/shopify_file_unavailable.md): Shopify did not send the picture
- [previous_secret](https://matrixrewards.co.uk/docs/errors/previous_secret.md): A key's previous secret cannot create a webhook endpoint