Billing, Usage Tracking, and Data Retention

AgentPost now includes a complete billing and usage tracking system powered by Stripe, along with data retention policies for message lifecycle management. All billing features are behind the BILLING_ENABLED feature flag -- self-hosted deployments can skip billing entirely.

Billing API

New billing endpoints give you full control over subscription management:

POST /billing/checkout -- Create a Stripe checkout session for new subscriptions
POST /billing/portal -- Generate a Stripe billing portal link for self-service management
GET /billing/subscription -- Retrieve the current org subscription status and plan details
POST /billing/subscription/change-plan -- Upgrade or downgrade with automatic proration
POST /billing/subscription/cancel -- Cancel with immediate or end-of-period options

A Stripe webhook handler processes subscription lifecycle events (payment succeeded, payment failed, subscription updated, subscription deleted) and keeps your org state in sync automatically.

A dunning flow handles failed payments gracefully: a configurable grace period gives customers time to update their payment method, with automatic org suspension only after the grace period expires. Orgs are reinstated automatically when payment resumes.

Usage Tracking

Real-time per-org counters track five resource types:

Counter	Description
`messages_sent`	Outbound messages via API
`messages_received`	Inbound messages from SES
`storage_bytes`	Total attachment storage
`api_calls`	API request count
`webhook_deliveries`	Webhook delivery attempts

Retrieve current-period usage with limit information:

const usage = await client.organizations.getUsage("org_01JQ...");
// { messages_sent: { current: 1250, limit: 5000, percentage: 25 }, ... }

Configure soft and hard limits per org tier. Free tier defaults to hard limits (requests rejected at threshold); paid tiers default to soft limits (warning emitted, requests continue). Limits are customizable per org via the settings API.

AgentPost emits webhook events when usage crosses thresholds:

usage.warning -- Fired when a counter reaches the soft limit (e.g., 80% of plan allowance)
usage.exceeded -- Fired when a counter hits the hard limit

An alert check runs every 15 minutes for near-real-time limit enforcement.

Data Retention

Set a retention period for your organization's messages:

await client.organizations.updateRetentionPolicy("org_01JQ...", {
  retention_days: 90,
});

PUT /organizations/:id/retention-policy -- Set or update the retention period
GET /organizations/:id/export -- Full organization data export (messages, attachments, metadata)

Automatic cleanup workers run on schedule to delete expired messages and orphan attachments. Warning emails are sent before deletion begins so org owners can export data or adjust the policy.

Console Integration

The console billing page includes:

Current plan and subscription status
Plan comparison table with upgrade/downgrade actions
Invoice history with pagination
Usage dashboard with real-time counters and limit indicators
Dunning banner when payment issues require attention
Weekly usage summary emails for organization owners