Calculating Billing

Run a full line-item breakdown before issuing an invoice.

Why Calculate Before Invoicing

The calculation API lets you run the full billing computation — including tier breakdowns, flat fees, and all charges on a plan — without creating an invoice. This serves two purposes:

  1. Pre-invoice verification: Before charging a customer, confirm the calculated amount looks correct. Catch configuration errors before money moves.
  2. Customer-facing pricing previews: Build a live “what will I pay this month?” widget in your product, powered by real billing engine calculations.

POST /v1/pricing/calculate

The calculate endpoint runs a full billing calculation for a customer over a specified period and returns a detailed line-item breakdown.

1
2
3
4
5
6
7
8

curl -X POST "$ABAXUS_URL/v1/pricing/calculate" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z"
  }'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

{
  "calculation_id": "calc_01hx9kq2r3s4t5u6v7w8x9y0",
  "customer_id": "cust_acme",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "currency": "usd",
  "total_amount": 18749,
  "line_items": [
    {
      "charge_id": "chg_base_fee",
      "description": "Growth base fee",
      "pricing_model": "flat_fee",
      "amount": 4900,
      "quantity": 1
    },
    {
      "charge_id": "chg_api_calls",
      "description": "API Calls (tiered)",
      "pricing_model": "tiered",
      "metric_key": "api_calls",
      "total_quantity": 1374923,
      "amount": 13849,
      "tier_breakdown": [
        { "tier": 1, "up_to": 100000, "quantity": 100000, "unit_price": 0, "amount": 0 },
        { "tier": 2, "up_to": 1000000, "quantity": 900000, "unit_price": 0.0001, "amount": 9000 },
        { "tier": 3, "up_to": null, "quantity": 374923, "unit_price": 0.00005, "amount": 1875 }
      ]
    },
    {
      "charge_id": "chg_data_egress",
      "description": "Data Egress",
      "pricing_model": "per_unit",
      "metric_key": "data_egress_gb",
      "total_quantity": 142.75,
      "unit_price": 0.08,
      "amount": 1142
    }
  ],
  "computed_at": "2026-04-03T10:20:00Z"
}

All monetary amounts are in cents (integer). 18749 = $187.49.

The calculation_id is a stable reference to this specific calculation run. When you subsequently create an invoice with POST /v1/invoices, you can pass the calculation_id to skip recomputation and use the pre-calculated amounts directly. This ensures the invoice reflects exactly what you previewed.

Understanding Tier Breakdowns

For tiered and volume charges, the tier_breakdown array shows exactly how each usage band was priced. In the example above, 1,374,923 API calls were priced as:

  • First 100,000: free ($0)
  • Next 900,000 (100k–1M): $0.0001 each = $90.00
  • Remaining 374,923 (above 1M): $0.00005 each = $18.75

Total for API calls: $138.49

This breakdown is included in the invoice and can be shown directly to customers in a usage report or invoice breakdown UI.

POST /v1/pricing/preview — For Pricing Pages

The preview endpoint is a lighter-weight version of calculate, designed for real-time pricing page use cases where you want to show customers what they’d pay at different usage levels without needing a real customer ID.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl -X POST "$ABAXUS_URL/v1/pricing/preview" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_growth",
    "hypothetical_usage": {
      "api_calls": 500000,
      "data_egress_gb": 50
    }
  }'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "plan_id": "plan_growth",
  "plan_version": 2,
  "currency": "usd",
  "total_amount": 9350,
  "line_items": [
    { "description": "Growth base fee", "amount": 4900 },
    { "description": "API Calls — 500k calls", "amount": 4000 },
    { "description": "Data Egress — 50 GB", "amount": 400 },
    { "description": "First 100k API calls free", "amount": 0 }
  ]
}

Use this on your pricing page to power an interactive “calculate your bill” widget. Pass hypothetical usage values from slider inputs and render the result without creating any customer records.