# Billing

Usage against the plan, and the recorded plan.

Part of [the API reference, version 2026-10](https://matrixrewards.co.uk/docs/api/2026-10.md). Every address below starts with the base address:

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

## Orders that earned points this billing month, against the plan's cap {#getUsage}

`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](https://matrixrewards.co.uk/docs/api/2026-10.md#headers).

### Example

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

The answer:

```json
{
  "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"
}
```

### Other answers

| Status | What it means | Error pages |
| --- | --- | --- |
| 401 | `unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer. | [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md) |
| 403 | `forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which. | [forbidden_scope](https://matrixrewards.co.uk/docs/errors/forbidden_scope.md) |
| 429 | `rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait. | [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md) |

## The subscriptions recorded for this account {#getPlan}

`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](https://matrixrewards.co.uk/docs/api/2026-10.md#headers).

### Example

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

The answer:

```json
{
  "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"
}
```

### Other answers

| Status | What it means | Error pages |
| --- | --- | --- |
| 401 | `unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer. | [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md) |
| 403 | `forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which. | [forbidden_scope](https://matrixrewards.co.uk/docs/errors/forbidden_scope.md) |
| 429 | `rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait. | [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md) |

---

Page: https://matrixrewards.co.uk/docs/api/2026-10/billing
Contract: 2026-10 sha256:35af153960028890fea5738799f5a71e535e1eea4dd3f6b8d5f50b37f02363da