GET
/api/v1/billing/subscription
Get current subscription details for the organization.
Parameters
| Name | Type | Required | Description |
|---|
authenticated_context | context | Optional | None required (uses authenticated org context) |
Response Fields
| Name | Type | Required | Description |
|---|
plan | string | Optional | Current plan name (free, starter, professional, enterprise) |
status | string | Optional | active, trialing, past_due, canceled |
current_period_start | string | Optional | ISO 8601 date |
current_period_end | string | Optional | ISO 8601 date |
seats_used | integer | Optional | Number of active seats |
seats_limit | integer | Optional | Maximum seats for plan |
Example Response
{
"plan": "plan value",
"status": [],
"current_period_start": "current period start value",
"current_period_end": "current period end value",
"seats_used": 42,
"seats_limit": 42
}
POST
/api/v1/billing/subscription/upgrade
Upgrade to a higher plan tier.
Parameters
| Name | Type | Required | Description |
|---|
plan | string | Required | Target plan name |
billing_cycle | string | Optional | monthly or annual, default monthly |
Response Fields
| Name | Type | Required | Description |
|---|
plan | string | Optional | New plan name |
effective_date | string | Optional | When the upgrade takes effect |
prorated_amount | number | Optional | Prorated charge for current period |
Example Response
{
"plan": "plan value",
"effective_date": "2026-05-08T12:00:00Z",
"prorated_amount": 42
}
GET
/api/v1/billing/invoices
List all invoices for the organization.
Parameters
| Name | Type | Required | Description |
|---|
status | string | Optional | Filter by paid, open, void |
limit | integer | Optional | Number of invoices to return, default 10 |
Response Fields
| Name | Type | Required | Description |
|---|
invoices | array | Optional | List of invoice objects |
total | integer | Optional | Total invoice count |
Example Response
{
"invoices": [],
"total": 42
}
GET
/api/v1/billing/invoices/{invoice_id}
Get details for a specific invoice.
Parameters
| Name | Type | Required | Description |
|---|
invoice_id | string | Required | Invoice identifier |
Response Fields
| Name | Type | Required | Description |
|---|
id | string | Optional | Invoice ID |
amount | number | Optional | Total amount |
currency | string | Optional | Three-letter currency code |
status | string | Optional | Payment status |
line_items | array | Optional | Itemized charges |
created_at | string | Optional | Invoice date |
Example Response
{
"id": "id_123",
"amount": 42,
"currency": "currency value",
"status": [],
"line_items": [],
"created_at": "created at value"
}
POST
/api/v1/billing/payment-methods
Add a new payment method.
Parameters
| Name | Type | Required | Description |
|---|
type | string | Required | card or bank_account |
token | string | Required | Payment processor token |
Response Fields
| Name | Type | Required | Description |
|---|
id | string | Optional | Payment method ID |
type | string | Optional | Method type |
last4 | string | Optional | Last 4 digits |
is_default | boolean | Optional | Whether set as default |
Example Response
{
"id": "id_123",
"type": "type value",
"last4": "last4 value",
"is_default": true
}