API Tara: billing
Plans and payment through Paddle (the Paddle webhook POST /v1/billing/paddle/webhook is outside this contract because it needs the raw body for the signature)
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/billing/plansPlans and prices, and what the browser needs for Paddle.js (public)
Public. The prices come from pricing/plans.json, the same file the pricing page is built from. billingEnabled is false when the server runs with TARA_BILLING_ENABLED off: nothing can be bought and clientToken is empty. clientToken is the browser-side Paddle token (not a secret).
No sign-in required.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Plans | application/json · object |
Example response
{
"billingEnabled": false,
"environment": "sandbox",
"clientToken": "string",
"currency": "USD",
"yearlyDiscountPercent": 0,
"plans": [
{
"id": "free",
"name": "string",
"monthly": 0,
"yearly": 0,
"features": []
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/billing/plans"/v1/orgs/{org}/billingPlan, subscription, seats, next period and last invoice of the organization (owner or admin)
plan changes only when the Paddle webhook (or the hourly reconciliation) says so, never because the browser says a payment went through. seats.paid is the quantity Paddle bills (0 without a subscription). overLimit is true when the plan is Free and the organization has more seats than it allows: nobody is removed, but no one can be added until seats are freed. checkout is the open checkout (a Paddle transaction waiting for payment) if any. canManage is true for owners: only they see the payment buttons.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Billing state | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Example response
{
"enabled": false,
"plan": "free",
"status": "active",
"interval": "monthly",
"seats": {
"used": 0,
"paid": 0,
"limit": 0,
"overLimit": false
},
"hasCustomer": false,
"canManage": false
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/billing" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/billing/checkoutOpen (or get back) the checkout of a plan (owner)
Requires the header Idempotency-Key (8 to 128 characters of letters, digits, -, _; generate one per click): the same key with the same body returns the stored answer and creates nothing; the same key with a different body is 422 idempotency_key_reused; the same key while the first request is still running is 409 idempotency_in_progress. Keys are kept 24 hours. The organization row is locked: an organization that already has a live subscription gets 409 already_subscribed; an open checkout younger than 30 minutes (same plan and interval) is returned again (reused: true) instead of creating a second Paddle transaction. 503 billing_unavailable when billing is off. Open Paddle.js with transactionId.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Idempotency-Key | header | string | yes |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
plan | team | yes | |
interval | monthly | yearly | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The checkout | application/json · object |
| 400 | Invalid input (error code in code) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
| 409 | Conflict (already_subscribed, idempotency_in_progress) | application/problem+json · object |
| 422 | Idempotency-Key reused with a different body | application/problem+json · object |
| 502 | Paddle did not answer | application/problem+json · object |
| 503 | Billing is off (billing_unavailable) | application/problem+json · object |
Example response
{
"transactionId": "string",
"plan": "string",
"interval": "monthly",
"quantity": 0,
"expiresAt": "2026-11-01T00:00:00Z",
"reused": false
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/billing/checkout" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"plan":"team","interval":"monthly"}'/v1/orgs/{org}/billing/portalOpen a Paddle customer portal session (owner)
A one-time link where the owner changes the card, reads invoices and cancels (cancellation takes effect at the end of the paid period). 409 no_customer before the first payment.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The portal link | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
| 409 | No customer yet (no_customer) | application/problem+json · object |
| 502 | Paddle did not answer | application/problem+json · object |
| 503 | Billing is off | application/problem+json · object |
Example response
{
"url": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/billing/portal" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/billing/paymentsPayment history of the organization (owner or admin)
Completed and other transactions copied from Paddle, newest first (date, invoice number, amount, status). Invoices as PDF stay in the Paddle portal (POST /v1/orgs/{org}/billing/portal).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
limit | query | integer | ||
cursor | query | string | Cursor from the previous page nextCursor |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | One page of payments | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Example response
{
"items": [
{
"transactionId": "string",
"invoiceNumber": "string",
"amount": 0,
"currency": "string",
"status": "string"
}
],
"nextCursor": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/billing/payments" \
-H "Authorization: Bearer $TARA_TOKEN"