Skip to main content

Billing & Usage API

The Billing API provides access to transaction usage tracking, subscription management, and plan configuration.

Endpoints​

OperationMethodEndpoint
Get Transaction UsageGET/api/usage/transactions
Get Usage HistoryGET/api/usage/transactions/history
Get Transaction ConfigGET/api/subscriptions/{orgId}/transaction-config
Update Transaction ConfigPUT/api/subscriptions/{orgId}/transaction-config
Get SubscriptionGET/api/stripe/subscription
Create CheckoutPOST/api/stripe/create-checkout-session
Create Portal SessionPOST/api/stripe/create-portal-session
List Plan ConfigsGET/api/plan-configurations
Update Plan ConfigPUT/api/plan-configurations/{planKey}

Transaction Usage​

Get Current Usage​

Returns the organization's transaction count for the current billing period.

GET /api/usage/transactions

Response:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "currentCount": 73,
  "limit": 100,
  "percentUsed": 73,
  "overagePolicy": "hard_limit",
  "isOverLimit": false,
  "period": "2026-03"
}
FieldDescription
currentCountTransactions processed this billing period
limitMaximum allowed by the plan
percentUsedUsage as a percentage
overagePolicyhard_limit (reject) or warn (allow with warning)
isOverLimitWhether the org has exceeded its limit
periodCurrent billing period (YYYY-MM)

Get Usage History​

Returns monthly transaction counts for the past N months.

GET /api/usage/transactions/history?months=6

Query Parameters:

ParameterTypeDefaultDescription
monthsinteger12Number of months (max 24)

Response:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "history": [
    { "period": "2026-03", "count": 73 },
    { "period": "2026-02", "count": 95 },
    { "period": "2026-01", "count": 42 },
    { "period": "2025-12", "count": 88 },
    { "period": "2025-11", "count": 56 },
    { "period": "2025-10", "count": 31 }
  ]
}

Transaction Configuration​

Transaction limits and overage policies are stored directly on the Subscription record. They are set automatically from PlanConfiguration defaults when a subscription is created or the plan changes, and can be overridden per-organization.

Get Config​

GET /api/subscriptions/{orgId}/transaction-config

Response:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "organizationName": "Acme Corp",
  "transactionLimit": 100,
  "overagePolicy": "hard_limit",
  "planKey": "free"
}

Update Config​

System administrators can adjust transaction limits and overage behavior per organization. Both fields are required to be non-null values.

PUT /api/subscriptions/{orgId}/transaction-config
Content-Type: application/json

{
  "transactionLimit": 500,
  "overagePolicy": "warn"
}
FieldTypeConstraints
transactionLimitintegerNon-negative integer (required, cannot be null)
overagePolicystringOne of: hard_limit, warn (required, cannot be null)
Real-time propagation

When the transaction config is updated, a notification is published via Redis pub/sub so the Stream Consumer immediately re-evaluates the org's limit without waiting for the 5-minute cache refresh.

Subscription Management​

When a subscription is created or its plan changes (via Stripe checkout, webhook, or admin action), the transactionLimit and overagePolicy fields are automatically set from the corresponding PlanConfiguration defaults. A notification is published via Redis pub/sub to the Stream Consumer for immediate enforcement.

Get Subscription Status​

GET /api/stripe/subscription?organizationId={id}

Response:

{
  "hasSubscription": true,
  "isActive": true,
  "subscription": {
    "id": "sub_xxxx",
    "status": "active",
    "planKey": "individual",
    "planName": "Individual",
    "currentPeriodEnd": "2026-04-05T00:00:00Z",
    "cancelAtPeriodEnd": false
  }
}

Create Checkout Session​

Initiate a Stripe checkout for a new subscription.

POST /api/stripe/create-checkout-session
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "planKey": "individual"
}

Response:

{
  "url": "https://checkout.stripe.com/c/pay/cs_xxxx..."
}

Create Portal Session​

Open the Stripe customer portal for subscription management.

POST /api/stripe/create-portal-session
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "url": "https://billing.stripe.com/p/session/xxxx..."
}

Plan Configuration (System Admin)​

List Plan Configurations​

GET /api/plan-configurations

Response:

[
  {
    "id": "plan-uuid-1",
    "planKey": "free",
    "displayName": "Free",
    "transactionLimit": 100,
    "overagePolicy": "hard_limit"
  },
  {
    "id": "plan-uuid-2",
    "planKey": "individual",
    "displayName": "Individual",
    "transactionLimit": -1,
    "overagePolicy": "warn"
  },
  {
    "id": "plan-uuid-3",
    "planKey": "team",
    "displayName": "Team",
    "transactionLimit": -1,
    "overagePolicy": "warn"
  }
]

A transactionLimit of -1 indicates unlimited transactions.

Update Plan Configuration​

PUT /api/plan-configurations/free
Content-Type: application/json

{
  "transactionLimit": 200,
  "overagePolicy": "hard_limit"
}
Real-time propagation

Updating a plan configuration broadcasts a notification to all organizations via Redis pub/sub, triggering the Stream Consumer to re-evaluate every org's transaction limit immediately.

curl Examples​

# Get current usage
curl -X GET "https://console.rocketwavelabs.io/api/usage/transactions" \
  -H "Cookie: appSession=YOUR_SESSION"

# Get 6-month history
curl -X GET "https://console.rocketwavelabs.io/api/usage/transactions/history?months=6" \
  -H "Cookie: appSession=YOUR_SESSION"

# Create checkout session
curl -X POST "https://console.rocketwavelabs.io/api/stripe/create-checkout-session" \
  -H "Content-Type: application/json" \
  -H "Cookie: appSession=YOUR_SESSION" \
  -d '{"organizationId": "YOUR_ORG_ID", "planKey": "individual"}'