Billing API

The Billing API provides endpoints for managing your organization's subscription through Stripe. All endpoints except the webhook require authentication.

Base path: /api/v1/billing

---

Create Checkout Session

Create a Stripe Checkout session to subscribe to a plan or upgrade.

POST /api/v1/billing/checkout

Request Body

Field	Type	Required	Description
plan	string	✅	Plan to subscribe to. One of: team, business

Example Request

curl -X POST https://roundtable.foxtrotcommunications.net/api/v1/billing/checkout \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"plan": "business"}'

Example Response

// 200 OK
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_abc123...",
  "sessionId": "cs_live_abc123def456"
}

Redirect the user to the returned url to complete the checkout process. After payment, Stripe redirects back to the Roundtable dashboard.

:::info Enterprise Plans Enterprise plans are not available through self-service checkout. Contact the Roundtable team for custom pricing and provisioning. :::

---

Create Customer Portal Session

Create a Stripe Customer Portal session. The portal lets users manage their payment methods, view invoices, and cancel subscriptions.

POST /api/v1/billing/portal

Example Request

curl -X POST https://roundtable.foxtrotcommunications.net/api/v1/billing/portal \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Example Response

// 200 OK
{
  "url": "https://billing.stripe.com/p/session/bps_abc123..."
}

Redirect the user to the returned url to access the Stripe Customer Portal.

Portal capabilities:

• Update credit card or payment method
• View and download past invoices
• Cancel subscription
• Update billing email

---

Get Current Subscription

Retrieve the current subscription details for your organization.

GET /api/v1/billing/subscription

Example Request

curl https://roundtable.foxtrotcommunications.net/api/v1/billing/subscription \
  -H "Authorization: Bearer ${TOKEN}"

Example Response

// 200 OK
{
  "plan": "business",
  "status": "active",
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "tokenCredits": {
    "included": 1000000,
    "used": 342150,
    "remaining": 657850
  },
  "seats": {
    "included": 10,
    "used": 7,
    "extra": 0
  },
  "workspaces": 3
}

Response Fields

Field	Type	Description
plan	string	Current plan: team, business, or enterprise
status	string	Subscription status: active, trialing, past_due, canceled
currentPeriodStart	string	Start of the current billing period (ISO 8601)
currentPeriodEnd	string	End of the current billing period (ISO 8601)
tokenCredits.included	number	Monthly token credit allocation
tokenCredits.used	number	Token credits consumed this period
tokenCredits.remaining	number	Token credits remaining this period
seats.included	number	Seats included in the plan
seats.used	number	Seats currently occupied
seats.extra	number	Seats beyond the included count (billed at $8/seat/mo)
workspaces	number	Number of active workspaces

No Subscription

If the organization has no active subscription (e.g., on a free trial or expired):

// 200 OK
{
  "plan": "trial",
  "status": "trialing",
  "trialEnd": "2026-06-04T00:00:00.000Z",
  "tokenCredits": {
    "included": 500000,
    "used": 12500,
    "remaining": 487500
  },
  "seats": {
    "included": 10,
    "used": 2,
    "extra": 0
  },
  "workspaces": 1
}

---

Stripe Webhook

Roundtable receives subscription lifecycle events from Stripe via webhook. This endpoint is called by Stripe, not by your application.

POST /api/billing/webhook

:::warning Not Versioned The webhook endpoint is at /api/billing/webhook (no /v1/ prefix). This is intentional — Stripe webhook URLs should remain stable across API versions. :::

How It Works

1. Stripe sends events (e.g., checkout.session.completed, invoice.paid, customer.subscription.deleted) to this endpoint.
2. Roundtable verifies the webhook signature using the Stripe webhook secret.
3. The event is processed and the organization's subscription state is updated.

Handled Events

Stripe Event	Roundtable Action
checkout.session.completed	Activate subscription, update plan
invoice.paid	Reset token credit usage, confirm billing
invoice.payment_failed	Mark subscription as past_due
customer.subscription.updated	Sync plan changes (upgrades/downgrades)
customer.subscription.deleted	Mark subscription as canceled

:::info For Roundtable Administrators Only You do not need to configure this webhook yourself — it is pre-configured in the Roundtable infrastructure. This documentation is provided for transparency and troubleshooting purposes. :::