---
title: "Retrieve plan"
description: "The shop's Invoice Falcon plan and this billing cycle's usage: the plan name, whether it is paid, the Free plan monthly invoice limit and how many orders have been invoiced against it, and when the cycle resets. Read-onl"
url: https://docs.invoicefalcon.com/v3-reference/account/retrieve-plan/
api: "API v3 reference"
method: GET
path: "/account/plan"
---

# Retrieve plan

`GET https://app.invoicefalcon.com/api/v3/external/account/plan`

The shop's Invoice Falcon plan and this billing cycle's usage: the plan name, whether it is paid, the Free plan monthly invoice limit and how many orders have been invoiced against it, and when the cycle resets. Read-only.

`tier` values: `free` (Free), `pro` (Pro), `partner` (Partner).

## Returns

- `tier` (string): e.g. `pro`
- `plan_name` (string): e.g. `ultimate`
- `price_per_month` (string): e.g. `9.99`
- `paid` (boolean): e.g. `true`
- `is_partner` (boolean): e.g. `true`
- `usage` (object)
  - `orders_invoiced_this_cycle` (integer): e.g. `1`
  - `monthly_limit` (integer): e.g. `50`
  - `remaining` (integer): e.g. `49`
  - `counted` (string): e.g. `An order counts once per cycle when one of its documents …`
  - `cycle_started_on` (string): e.g. `2026-11-10`
  - `cycle_resets_on` (string): e.g. `2026-12-10`

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

## Example request

```sh
curl "https://app.invoicefalcon.com/api/v3/external/account/plan" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

The requested resource.

```json
{
  "tier": "pro",
  "plan_name": "ultimate",
  "price_per_month": "9.99",
  "paid": true,
  "is_partner": true,
  "usage": {
    "orders_invoiced_this_cycle": 1,
    "monthly_limit": 50,
    "remaining": 49,
    "counted": "An order counts once per cycle when one of its documents is emailed, printed, downloaded or rendered; creating or listing invoices does not.",
    "cycle_started_on": "2026-11-10",
    "cycle_resets_on": "2026-12-10"
  }
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

