---
title: "Get plan usage"
description: "The shop's current STOQ plan, the limits it includes, and a calendar month's usage against them (back-in-stock email and SMS alerts, SMS segments, preorders)."
url: https://docs.stoqapp.com/v2-reference/account-plan-usage/get-plan-usage/
api: "API v2 reference"
method: GET
path: "/account/plan_usage"
---

# Get plan usage

`GET https://app.stoqapp.com/api/v2/external/account/plan_usage`

The shop's current STOQ plan, the limits it includes, and a calendar month's usage against them (back-in-stock email and SMS alerts, SMS segments, preorders).

**Note:** usage.by_template splits the month's back-in-stock email and SMS alerts by notification template, as the usage card's breakdown does. Each row's key names the notification (restock_alert, reminder), the same key as /back_in_stock/templates/:key. limits.unlimited_preorders is true when the plan has no preorder limit (preorder_limit 0). usage.preorders_over_limit is the month's preorders above preorder_limit.

## Query parameters

- `period` (string): Calendar month to report usage for, as YYYY-MM (e.g. 2026-04); defaults to the current month.

## Returns

- `plan` (object)
  - `name` (string, nullable): e.g. `pro_per_month`
  - `friendly_name` (string, nullable): e.g. `Pro`
  - `note` (string)
- `period` (object)
  - `month` (string): e.g. `2026-11`
  - `is_current` (boolean): e.g. `true`
- `limits` (object)
  - `usage_type` (string): e.g. `per_month`
  - `unlimited_notifications` (boolean): e.g. `false`
  - `notification_limit` (integer): e.g. `2000`
  - `email_limit` (integer): e.g. `0`
  - `sms_limit` (integer): e.g. `0`
  - `preorder_limit` (integer): e.g. `400`
- `usage` (object)
  - `email_alerts` (integer): e.g. `684`
  - `sms_alerts` (integer): e.g. `112`
  - `sms_segments` (integer): e.g. `131`
  - `total_alerts` (integer): e.g. `796`
  - `alerts_over_limit` (integer): e.g. `0`
  - `preorders` (integer): e.g. `57`
  - `by_template` (array of objects)
    - `template_position` (integer): e.g. `0`
    - `email_alerts` (integer): e.g. `521`
    - `sms_alerts` (integer): e.g. `98`

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
curl "https://app.stoqapp.com/api/v2/external/account/plan_usage" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: example response shown.

```json
{
  "plan": {
    "name": "pro_per_month",
    "friendly_name": "Pro"
  },
  "period": {
    "month": "2026-11",
    "is_current": true
  },
  "limits": {
    "usage_type": "per_month",
    "unlimited_notifications": false,
    "notification_limit": 2000,
    "email_limit": 0,
    "sms_limit": 0,
    "preorder_limit": 400
  },
  "usage": {
    "email_alerts": 684,
    "sms_alerts": 112,
    "sms_segments": 131,
    "total_alerts": 796,
    "alerts_over_limit": 0,
    "preorders": 57,
    "by_template": [
      {
        "template_position": 0,
        "email_alerts": 521,
        "sms_alerts": 98
      },
      {
        "template_position": 1,
        "email_alerts": 163,
        "sms_alerts": 14
      }
    ]
  }
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

