> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saasybill.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a plan
Requires the `catalogue:read` scope. See [Authentication](/api-reference/authentication#scopes).
## OpenAPI
````yaml /api-reference/openapi.json get /v1/plans/{id}
openapi: 3.1.0
info:
title: Saasybill API
version: 1.0.0
description: >-
Create and manage subscriptions in Saasybill from your own platform.
Every request is authenticated with an API key sent as `Authorization:
Bearer saasybill_live_…`.
Writes accept an `Idempotency-Key` header. It is required to create a
subscription.
Webhooks, errors, pagination and idempotency are covered in the guides
alongside this reference.
servers:
- url: https://app.saasybill.com/api
description: Production
security: []
tags:
- name: Organisation
description: The organisation an API key belongs to.
- name: Customers
description: >-
Customers are synced from Xero. Create one only where the organisation
allows it.
- name: Plans
description: Read the pricing plans you can sell.
- name: Charges
description: Read the one-off fees that can be added to a new subscription.
- name: Subscriptions
description: Create subscriptions, change units, and end or restore them.
- name: Invoices
description: Read the invoices Saasybill raises in Xero.
paths:
/v1/plans/{id}:
get:
tags:
- Plans
summary: Retrieve a plan
operationId: get_v1_plans_id
parameters:
- name: id
in: path
required: true
schema:
type: string
example: b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44
description: The Saasybill id of the plan.
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
id:
type: string
object:
type: string
const: plan
code:
type: string
name:
type: string
type:
type: string
enum:
- flat_fee
- per_unit
- tiered
- volume
- stairstep
interval:
type: object
properties:
unit:
type: string
enum:
- day
- week
- month
- year
count:
type: integer
required:
- unit
- count
additionalProperties: false
currency:
type: string
price:
type: string
description: A decimal string, e.g. "19.9900".
minimum_units:
type: integer
free_units:
type: integer
unit_labels:
type: object
properties:
singular:
type:
- string
- 'null'
plural:
type:
- string
- 'null'
required:
- singular
- plural
additionalProperties: false
allows_price_override:
type: boolean
status:
type: string
enum:
- draft
- active
- inactive
- legacy
tiers:
type: array
items:
type: object
properties:
from_units:
type: integer
to_units:
anyOf:
- type: integer
- type: 'null'
price:
type: string
description: A decimal string, e.g. "19.9900".
required:
- from_units
- to_units
- price
additionalProperties: false
created:
type: string
format: date-time
description: ISO 8601, UTC.
required:
- id
- object
- code
- name
- type
- interval
- currency
- price
- minimum_units
- free_units
- unit_labels
- allows_price_override
- status
- tiers
- created
additionalProperties: false
example:
id: b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44
object: plan
code: TEAM-MONTHLY
name: Team
type: per_unit
interval:
unit: month
count: 1
currency: AUD
price: '12.0000'
minimum_units: 5
free_units: 0
unit_labels:
singular: seat
plural: seats
allows_price_override: false
status: active
tiers: []
created: '2026-06-02T23:10:44.000Z'
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
'401':
description: The key is missing, malformed, revoked or expired.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: authentication_error
code: invalid_api_key
message: 'Provide a valid API key as `Authorization: Bearer `.'
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'403':
description: >-
The key lacks the scope, is a test key, or the organisation has not
allowed this.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: permission_error
code: insufficient_scope
message: This API key does not have the `subscriptions:write` scope.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'404':
description: No such object.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: not_found
code: plan_not_found
message: There is no plan with that id.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'409':
description: >-
The request conflicts with the current state, or with an earlier
request using the same `Idempotency-Key`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: conflict
code: idempotency_conflict
message: >-
This `Idempotency-Key` was used with a different request.
Use a new key for a different request.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'422':
description: A field is missing or invalid. `error.param` names it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: invalid_request_error
code: invalid_parameter
message: '`units`: Invalid input: expected number, received string'
param: units
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'429':
description: 'Rate limited: 120 requests a minute per key. See `Retry-After`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: rate_limit_error
code: rate_limited
message: Too many requests. Try again in 12 seconds.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'500':
description: >-
Something went wrong on our side. Retry; quote `error.request_id` if
it persists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: api_error
code: internal_error
message: >-
Something went wrong on our side. Retry the request; if it
keeps failing, quote the request id.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
security:
- bearerAuth:
- catalogue:read
components:
headers:
Request-Id:
description: A unique id for the request. Quote it when you contact support.
schema:
type: string
example: req_4f1a9c2e7b8d3a605e1c9f02
RateLimit-Limit:
description: Requests allowed per minute for this key.
schema:
type: integer
example: 120
RateLimit-Remaining:
description: Requests left in the current window.
schema:
type: integer
example: 117
RateLimit-Reset:
description: Seconds until the oldest counted request stops counting.
schema:
type: integer
example: 41
schemas:
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
enum:
- authentication_error
- permission_error
- invalid_request_error
- not_found
- conflict
- rate_limit_error
- api_error
code:
type: string
description: Stable. Branch on this, never on `message`.
message:
type: string
param:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
additionalProperties: false
required:
- error
additionalProperties: false
description: >-
Every failed request answers with this shape. Branch on `error.code`,
never on `error.message`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
An API key. Its scopes decide what it may call: `customers:read` (List
and look up customers.) `customers:write` (Create customers, and Xero
contacts where the organisation allows it.) `catalogue:read` (List plans
and charges.) `subscriptions:read` (List and look up subscriptions.)
`subscriptions:write` (Create subscriptions, change units, end and
restore them.) `invoices:read` (List and look up invoices.)
````