Skip to content

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.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/billing/plans

Plans 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 ​

CodeDescriptionType
200Plansapplication/json · object

Example response ​

json
{
  "billingEnabled": false,
  "environment": "sandbox",
  "clientToken": "string",
  "currency": "USD",
  "yearlyDiscountPercent": 0,
  "plans": [
    {
      "id": "free",
      "name": "string",
      "monthly": 0,
      "yearly": 0,
      "features": []
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/billing/plans"
GET/v1/orgs/{org}/billing

Plan, 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 ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Billing stateapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "plan": "free",
  "status": "active",
  "interval": "monthly",
  "seats": {
    "used": 0,
    "paid": 0,
    "limit": 0,
    "overLimit": false
  },
  "hasCustomer": false,
  "canManage": false
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/billing" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/billing/checkout

Open (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 ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
Idempotency-Keyheaderstringyes

Body (application/json) ​

FieldTypeRequiredDescription
planteamyes
intervalmonthly | yearlyyes

Responses ​

CodeDescriptionType
200The checkoutapplication/json · object
400Invalid input (error code in code)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (already_subscribed, idempotency_in_progress)application/problem+json · object
422Idempotency-Key reused with a different bodyapplication/problem+json · object
502Paddle did not answerapplication/problem+json · object
503Billing is off (billing_unavailable)application/problem+json · object

Example response ​

json
{
  "transactionId": "string",
  "plan": "string",
  "interval": "monthly",
  "quantity": 0,
  "expiresAt": "2026-11-01T00:00:00Z",
  "reused": false
}

Call with curl ​

bash
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"}'
POST/v1/orgs/{org}/billing/portal

Open 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 ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The portal linkapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409No customer yet (no_customer)application/problem+json · object
502Paddle did not answerapplication/problem+json · object
503Billing is offapplication/problem+json · object

Example response ​

json
{
  "url": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/billing/portal" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/billing/payments

Payment 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 ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
limitqueryinteger
cursorquerystringCursor from the previous page nextCursor

Responses ​

CodeDescriptionType
200One page of paymentsapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "transactionId": "string",
      "invoiceNumber": "string",
      "amount": 0,
      "currency": "string",
      "status": "string"
    }
  ],
  "nextCursor": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/billing/payments" \
  -H "Authorization: Bearer $TARA_TOKEN"