Billing

Usage against the plan, and the recorded plan.

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

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

Orders that earned points this billing month, against the plan's cap

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

Needs: the read_usage permission (in the app: “Orders used this month and which plan you are on”).

The plan comes from the subscription this platform has recorded from Shopify's billing webhooks, not from a live call to Shopify.

The answer

Usage this month.

Field	Type	Always there	What it is
`used`	integer	yes	—
`cap`	integer, or null	yes	Null when no cap applies, or when the level says we could not tell.
`percent`	integer, or null	yes	—
`level`	one of `ok`, `approaching`, `over`, `unknown`	yes	—
`counts`	string	yes	What `used` counts, said in the response and not only in the docs.
`month`	object	yes	—
`month.label`	string	yes	—
`month.from`	string	yes	—
`month.to`	string	yes	—
`plan_source`	one of `recorded_subscription`	yes	—
`plan_name`	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/usage" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "used": 0,
  "cap": null,
  "percent": null,
  "level": "ok",
  "counts": "orders that earned points",
  "month": {
    "label": "2026-09",
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-10-01T00:00:00.000Z"
  },
  "plan_source": "recorded_subscription",
  "plan_name": "Multi-store wallet"
}

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
429	`rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait.	rate_limited

The subscriptions recorded for this account

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

Needs: the read_usage permission (in the app: “Orders used this month and which plan you are on”).

A read, and only a read. A plan is changed on Shopify's own page.

The answer

The recorded subscriptions.

Field	Type	Always there	What it is
`data`	list of object	yes	—
`data[].store_key`	string	yes	—
`data[].plan_name`	string	yes	—
`data[].status`	string	yes	—
`data[].price`	object	yes	—
`data[].price.amount`	string	yes	Decimal, as text: a price that has been through binary floating point is not a price.
`data[].price.currency`	string	yes	—
`data[].billing_interval`	string	yes	—
`data[].trial_days`	integer	yes	—
`data[].is_test`	boolean	yes	—
`data[].capabilities`	list of string	yes	—
`data[].activated_at`	string, or null	yes	—
`has_more`	boolean	yes	—
`next_cursor`	string, or null	yes	—
`change_plan_at`	string	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/plan" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "data": [
    {
      "store_key": "example-store",
      "plan_name": "Multi-store wallet",
      "status": "active",
      "price": {
        "amount": "79.00",
        "currency": "USD"
      },
      "billing_interval": "EVERY_30_DAYS",
      "trial_days": 14,
      "is_test": false,
      "capabilities": [
        "shared_wallet"
      ],
      "activated_at": "2026-08-03T09:20:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "change_plan_at": "the app in your Shopify admin"
}

Billing

Orders that earned points this billing month, against the plan's cap

The answer

Example

Other answers

The subscriptions recorded for this account

The answer

Example

Other answers