Your own use of HatchPay is governed by a subscription. The Tenant Billing service manages plans, subscriptions, and payment configuration, while the Billing Processor service runs in the background to meter usage and generate invoices. This page explains how those pieces fit together; plan selection and payment entry happen during onboarding.

Subscription Plans

A plan defines the price and entitlements for a tier of service. Plans combine a flat recurring price (monthly, quarterly, or yearly) with optional usage-based pricing for metered activity.

GET /v1/billing/subscription-plans/{plan_id} — retrieve a plan by its identifier.

GET /v1/billing/subscription-plans/code/{plan_code} — look up a plan by its human-readable code.

Each plan response includes its tier, billing period, active status, and the nested pricing options and usage metrics that apply.

Your Subscription

A tenant has at most one active subscription at a time. A new subscription begins in a PENDING_PAYMENT state, transitions to ACTIVE once payment is confirmed, and ends in CANCELED when cancelled (either immediately or at the end of the current period).

GET /v1/billing/tenant-subscriptions/active — retrieve your current active subscription, including the plan details and any applied discount.

GET /v1/billing/tenant-subscriptions — list your subscriptions, optionally filtered by status.

POST /v1/billing/tenant-subscriptions/{id}/cancel — cancel a subscription.

How Usage Is Metered & Billed

The Billing Processor service runs scheduled jobs that turn raw activity into invoices:

• Usage aggregation rolls individual usage events up into per-metric totals for each subscription.
• Invoice generation runs on each subscription’s billing date and produces an invoice whose total is the plan’s base charge plus any aggregated usage charges, broken out into line items (base fee, per-unit usage, and tiered adjustments).
• Renewal advances a subscription’s billing period when a cycle completes.
• Retry reprocesses invoices whose payment previously failed.

Because invoicing is driven by your subscription’s billing date rather than by a fixed calendar day, charges appear on the cycle defined by your plan. Usage that is metered mid-cycle is aggregated and reflected on the next invoice.