Core Concepts

The mental model behind ABAXUS — metrics, plans, events, aggregates, and invoices.

The Six Core Objects

ABAXUS is built around six objects that form a clean pipeline from usage signal to paid invoice. Understanding how they relate to each other is the foundation for building a correct billing integration.

Metrics

A metric defines what you want to measure and how to aggregate raw events into a usage total for a billing period.

Every metric has a key (a stable string identifier like api_calls or active_seats), an aggregation type, and a display name. The aggregation type determines how raw event values are collapsed into a single number:

  • sum — add all event values (total API calls, total data transferred)
  • count — count the number of events regardless of value (number of requests)
  • max — take the highest value seen in the period (peak concurrent users)
  • min — take the lowest value seen (rarely used, but valid)
  • last — take the most recent value (current seat count, storage size)
  • unique_count — count distinct values of a specified property (unique users, unique IP addresses)
  • percentile — compute a percentile (p95 latency, p99 throughput)

Metrics are created once and referenced by key everywhere else. Deactivating a metric prevents new events from being recorded against it but preserves all historical data and aggregates.

Price Plans

A price plan defines how to charge for measured usage. It contains one or more charges, each referencing a metric and a pricing model. Plans also carry entitlement definitions — the feature flags and limits that customers on this plan receive.

Plans are versioned and immutable. Once a plan is published, you can’t change it. To update pricing, you create a new version of the same plan. Existing subscriptions continue to reference their locked version, protecting historical billing consistency.

The five pricing models available for charges:

  • per_unit — a fixed price per unit of usage
  • tiered — different unit prices for different usage ranges (each tier applies only to usage within that range)
  • volume — the unit price is determined by which tier the total usage falls into (applies that price to all units)
  • package — charge per block of N units (e.g., $10 per 1,000 calls)
  • flat_fee — a fixed amount regardless of usage (base fee, seat fee)

A single plan can mix multiple pricing models across different metrics.

Customers

A customer represents an entity you bill — typically a company or organization in a B2B context, or a user in a B2C context. Each customer has a stable id you define (matching your own user or organization ID), an email address, and one or more payment methods attached through your configured payment provider (Stripe or Adyen).

Customers are the billing subjects. Every event, subscription, and invoice is associated with a customer ID.

Subscriptions

A subscription binds a customer to a specific version of a price plan. When you create a subscription, ABAXUS records the current version number of the plan and pins the subscription to it. All billing calculations for that subscription use that locked version.

Subscriptions have a start_date and an optional end_date. They activate entitlements immediately — as soon as a subscription is created, GET /v1/entitlements reflects the plan’s entitlement definitions for that customer.

A customer can have multiple concurrent subscriptions on different plans (for example, a base platform subscription and an add-on). ABAXUS resolves entitlements across all active subscriptions when you query the check endpoint.

Events

Events are the raw usage signals your product emits. Each event has:

  • customer_id — who generated the usage
  • metric_key — which metric this event contributes to
  • value — the numeric magnitude (1 for a single API call, 512 for 512 MB transferred)
  • timestamp — when the usage occurred (can be in the past for backfill)
  • idempotency_key — a unique identifier for this event submission (mandatory)

Events are the only input to the metering system. ABAXUS aggregates them into usage totals when billing calculations run. The same event submitted twice (same idempotency_key) is silently deduplicated — no double-counting.

Events are processed asynchronously. A 202 Accepted response means the event is queued, not yet aggregated. Use POST /v1/usage/compute for an exact, synchronous usage total when you need it.

Invoices

Invoices are the output of the billing cycle. When you call POST /v1/invoices, ABAXUS:

  1. Looks up all active subscriptions for the customer
  2. Determines the billing period based on the subscription’s start_date and the cutoff_date you provide
  3. Computes usage totals for each metered charge by aggregating events in that period
  4. Applies the plan’s pricing rules to produce a monetary amount per charge
  5. Returns an invoice with full line items and a total

The invoice lifecycle follows a state machine: issued → paid (or archived). An issued invoice can be charged (POST /v1/invoices/:id/charge), which transitions it to paid on success. Invoices can also be archived if you decide not to collect (for example, a zero-amount invoice, or a billing dispute resolution).

Every state transition is recorded in the invoice’s audit trail (GET /v1/invoices/:id/events), giving you a complete history of what happened and when.