Billing

The billing endpoints manage subscription tiers, Stripe Checkout sessions, customer portal access, and billing event audit trails. All endpoints except the webhook require authentication.

GET/billing/planAuthenticated

Returns the current billing tier, feature limits, and usage counts.

curl http://127.0.0.1:7741/billing/plan \
  -H "Authorization: Bearer $TOKEN"

200Response

{
  "ok": true,
  "data": {
    "tier": "free",
    "label": "Free",
    "status": "active",
    "email": null,
    "connectors": {
      "used": 1,
      "limit": 2
    },
    "triggers": {
      "used": 2,
      "limit": 3
    },
    "pastDue": false,
    "gracePeriod": false,
    "validUntil": null
  }
}

POST/billing/checkoutAuthenticated

Creates a Stripe Checkout session and returns a redirect URL.

Parameter	Type	Required	Description
`email`	`string`	Yes	Customer email for the checkout session
`client_ip`	`string`	No	Client IP address for tax calculation
`user_agent`	`string`	No	Client user agent string

curl -X POST http://127.0.0.1:7741/billing/checkout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

200Response

{
  "ok": true,
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_live_..."
  }
}

POST/billing/portalAuthenticated

Creates a Stripe Customer Portal session for managing the subscription.

Parameter	Type	Required	Description
`customer_id`	`string`	No	Stripe customer ID (uses current subscription if omitted)

curl -X POST http://127.0.0.1:7741/billing/portal \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_..."
  }'

200Response

{
  "ok": true,
  "data": {
    "url": "https://billing.stripe.com/p/session/..."
  }
}

GET/billing/eventsAuthenticated

Returns an audit trail of billing events.

Parameter	Type	Required	Description
`limit`	`number`	No	Max events to return (query param)
`type`	`string`	No	Filter by event type (query param)
`include_payload`	`boolean`	No	Include raw Stripe payload (query param)

curl "http://127.0.0.1:7741/billing/events?limit=10&type=checkout.session.completed" \
  -H "Authorization: Bearer $TOKEN"

200Response

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "type": "checkout.session.completed",
      "stripe_event_id": "evt_...",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}

POST/billing/webhook

Stripe webhook endpoint. Verified via Stripe signature header, not Bearer auth.

This endpoint is called by Stripe to deliver subscription lifecycle events (checkout completed, invoice paid, subscription updated/deleted). It verifies the Stripe-Signature header against your configured webhook secret. No Bearer token is required.

Tiers

Tier	Connectors	Triggers
`free`	2	3
`pro`	10	Unlimited
`team`	Unlimited	Unlimited
`enterprise`	Unlimited	Unlimited