How It Works — ABAXUS API Walkthrough

Setup

Configure your infrastructure and customer metering

~4 API calls to go live

Infrastructure

Define Metrics POST /v1/metrics

Declare what to measure — API calls, storage bytes, active seats. Each metric specifies an aggregation type: sum, count, max, unique_count, and more.

Create Price Plans POST /v1/price-plans

Attach charges to metrics using a pricing model: per-unit, tiered, volume, package, or flat fee. Plans are immutable — a new version is created each time you re-use the same plan ID, so existing subscriptions are never broken.

Customer Metering

Create customer records with Stripe credentials and a default payment method attached. The Stripe cus_xxx ID must be provided alongside the payment method to enable reuse across invoices.

Create Subscriptions POST /v1/subscriptions

Bind a customer to a price plan with a start date. The current plan version is pinned at creation — future plan updates never touch this subscription.

setup.sh

# 1. Define what to measure
curl -X POST $API/v1/metrics \
  -d '{
    "key": "api_calls",
    "aggregation_type": "sum",
    "value_type": "integer"
  }'

# 2. Define how to charge
curl -X POST $API/v1/price-plans \
  -d '{
    "id": "plan_growth", "currency": "USD",
    "charges": [{
      "metric_key": "api_calls",
      "model": "tiered",
      "properties": {
        "tiers": [
          {"up_to":10000,"unit_amount":"0.001"},
          {"up_to":null, "unit_amount":"0.0005"}
        ]
      }
    }]
  }'

# 3. Register the customer
curl -X POST $API/v1/customers \
  -d '{
    "id": "cust_acme",
    "billing": {"provider":"stripe",...},
    "payment_method": {
      "provider_customer_id": "cus_xxx",
      "provider_payment_method": "pm_xxx"
    }
  }'

# 4. Activate the subscription
curl -X POST $API/v1/subscriptions \
  -d '{
    "customer_id": "cust_acme",
    "plan_id": "plan_growth",
    "start_date": "2026-01-01T00:00:00Z"
  }'

# → {"id":"sub_a1b2c3","status":"active"}

Full reference → Metrics, Price Plans, Customers, Subscriptions

Ingestion

Stream usage signals into ABAXUS in real time

Every billable action in your product becomes an event. ABAXUS accepts single events, batches of up to 500, and historical backfills — all idempotent. One invalid event in a batch never blocks the rest.

POST /v1/events → 202

Single event — queued async, never blocks your request path. Returns immediately with 202 Accepted.

POST /v1/events/batch → 207

Up to 500 events per call — each item has its own status in the 207 Multi-Status response. Maximises throughput at high volume.

POST /v1/events/backfill

Bypasses the async queue and writes directly to the events table. Automatically invalidates affected pre-computed aggregates. Use for data migrations.

Mandatory idempotency

Every event requires an idempotency_key. Duplicate keys are silently skipped — safe to retry unconditionally on any network failure or timeout.

ingest.sh

# Single event — fire and forget
curl -X POST $API/v1/events \
  -d '{
    "customer_id":     "cust_acme",
    "subscription_id": "sub_a1b2c3",
    "metric_key":      "api_calls",
    "value":           "1",
    "timestamp":       "2026-03-17T14:00:00Z",
    "idempotency_key": "evt_req_abc123",
    "properties": { "region": "us-east-1" }
  }'

# → 202 Accepted

# Batch — up to 500 at once
curl -X POST $API/v1/events/batch \
  -d '{
    "events": [
      {"idempotency_key":"evt_001",...},
      {"idempotency_key":"evt_002",...}
    ]
  }'

# → 207 {"results":[{"status":202},...]}

Full reference → Events, Usage, Histogram

Invoicing

Automated billing from usage to payment

Check usage GET /v1/usage/summary

Query pre-computed aggregates for a customer-facing dashboard view. Or call POST /v1/usage/compute for the exact authoritative figure that will appear on the invoice.

Calculate billing POST /v1/pricing/calculate

Run a full line-item calculation for the billing period. Every tier, every metric broken down. The resulting calculation_id is stored and referenced in the invoice.

Issue invoice POST /v1/invoices

Create an invoice. cutoff_date becomes the period end; the period start is derived from the last invoice or subscription start date. Invoices with a $0 total are rejected.

Charge payment POST /v1/invoices/:id/charge

Create a Stripe PaymentIntent for the invoice total using the customer's saved payment method. On success the invoice transitions to paid.

Invoice lifecycle

issued send-email → charge → paid | → archive → archived

invoice.sh

# A. Check current usage
curl $API/v1/usage/summary\
  ?customer_id=cust_acme\
  &metric_key=api_calls\
  &period_start=2026-03-01T00:00:00Z\
  &period_end=2026-04-01T00:00:00Z

# → {"value":"85000","meta":{"consistency":"eventual"}}

# B. Calculate exact billing
curl -X POST $API/v1/pricing/calculate \
  -d '{
    "customer_id":"cust_acme",
    "subscription_id":"sub_a1b2c3",
    "period_start":"2026-03-01T00:00:00Z",
    "period_end":"2026-04-01T00:00:00Z"
  }'

# → {"total_amount":"127.50","line_items":[...]}

# C. Issue the invoice
curl -X POST $API/v1/invoices \
  -d '{
    "customer_id":"cust_acme",
    "cutoff_date":"2026-03-31T23:59:59Z"
  }'

# → {"id":"inv_abc","status":"issued"}

# D. Charge the customer
curl -X POST $API/v1/invoices/inv_abc/charge

# → {"status":"paid","payment_intent":"pi_xxx"}

Full reference → Usage, Pricing, Invoices

From deployment to
paid invoice.

Setup

Ingestion

Invoicing

Ready to go deeper?

From deployment topaid invoice.

Setup

Ingestion

Invoicing

Ready to go deeper?

From deployment to
paid invoice.