API Reference
The Orbiill Public API provides programmatic access to plans, billing configs, and subscriptions. All endpoints require API key authentication.
Authentication
Authenticate by including your API key in the x-api-key header. Create and manage API keys in Settings → API Keys in the dashboard.
header
x-api-key: orb_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Security: Never expose your API key in client-side code. Always call the API from your backend server.
Base URL
https://api.orbiill.com/api/v1/Rate Limits
Rate limits are applied per API key. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.
| Endpoint | Rate Limit |
|---|---|
GET /plans, GET /plans/:id | 100 requests / minute |
GET /billing-configs, GET /billing-configs/:id | 100 requests / minute |
GET /subscriptions | 100 requests / minute |
POST /subscriptions/:id/cancel | 30 requests / minute |
POST /subscriptions/:id/usage | 60 requests / minute |
Endpoints
Plans
GET
/api/v1/plansList all plans for your organizationGET
/api/v1/plans/:idGet plan detailsList planscurl
curl https://api.orbiill.com/api/v1/plans \
-H "x-api-key: orb_sk_a1b2c3d4..."Response 200json
{
"data": [
{
"id": "bp_abc123",
"name": "Pro",
"description": "For growing teams",
"priceAmount": 29,
"currency": "USD",
"intervalUnit": "month",
"intervalCount": 1,
"features": ["Unlimited projects", "Priority support"],
"isFree": false,
"trialDays": 14
}
]
}Billing Configs
GET
/api/v1/billing-configsList billing configsGET
/api/v1/billing-configs/:idGet billing config detailsList billing configscurl
curl https://api.orbiill.com/api/v1/billing-configs \
-H "x-api-key: orb_sk_a1b2c3d4..."Subscriptions
GET
/api/v1/subscriptionsList subscriptionsPOST
/api/v1/subscriptions/:id/cancelCancel a subscriptionPOST
/api/v1/subscriptions/:id/usageReport usage for a subscription itemQuery parameters for GET /subscriptions
| Parameter | Type | Description |
|---|---|---|
cursor optional | string | Pagination cursor from meta.nextCursor |
limit optional | integer | Results per page (default: 25, max: 100) |
List subscriptionscurl
curl https://api.orbiill.com/api/v1/subscriptions?limit=10 \
-H "x-api-key: orb_sk_a1b2c3d4..."Response 200json
{
"data": [
{
"id": "sub_1N0abc...",
"customerEmail": "[email protected]",
"customerName": "John Doe",
"status": "active",
"currentPeriodEnd": "2026-05-08T00:00:00Z",
"cancelAtPeriodEnd": false,
"created": "2026-04-08T10:00:00Z",
"items": [
{
"priceId": "price_1N0...",
"productName": "Pro",
"unitAmountCents": 2900,
"currency": "usd",
"interval": "month",
"intervalCount": 1,
"quantity": 1
}
]
}
],
"meta": {
"hasMore": false,
"nextCursor": null
}
}Body parameters for POST /subscriptions/:id/cancel
| Parameter | Type | Description |
|---|---|---|
immediate optional | boolean | Cancel immediately (default: false, cancel at period end) |
Body parameters for POST /subscriptions/:id/usage
| Parameter | Type | Description |
|---|---|---|
quantity required | number | Usage quantity to report |
Report usagecurl
curl -X POST https://api.orbiill.com/api/v1/subscriptions/si_abc123/usage \
-H "x-api-key: orb_sk_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{ "quantity": 150 }'Response 200json
{
"data": { "success": true }
}Error Codes
All errors follow a consistent format:
Error responsejson
{
"message": "Billing config must be validated before deployment",
"statusCode": 400,
"error": "Bad Request"
}| Code | Name | Description |
|---|---|---|
400 | Bad Request | Request body failed validation. Check the message field. |
401 | Unauthorized | Missing or invalid API key. |
403 | Forbidden | You do not have permission. You may be accessing a resource outside your organization. |
404 | Not Found | The requested resource does not exist. |
429 | Too Many Requests | Rate limit exceeded. Check the Retry-After header. |
500 | Internal Server Error | Unexpected error. If it persists, contact support. |