Testing & Validation

Before going live with usage-based billing, validate your configuration end-to-end to ensure events are ingested correctly, addon price aggregation works as expected, and invoices reflect the right charges.

Testing Checklist

1. Validate Event Ingestion

• Send a test usage event via the API and confirm it appears in the Usage Events list
• Send a batch of events and verify all are received
• Send a duplicate event_id and confirm it is rejected with DUPLICATE status
• Send an event with missing required fields and confirm it is marked INVALID
• Upload a test CSV file and verify all rows are imported correctly
• Check that event properties are stored and filterable

2. Validate Addon Price UBB Configuration

• Create an addon price with Per Unit or Volume pricing model
• Configure the UBB fields: event type, aggregation method, aggregation property, and filters
• Verify the event type matches your usage events exactly (case-sensitive)
• For SUM/MIN/MAX/AVG, verify the aggregation property matches a property in your events
• Test filter conditions by sending events that should and should not match
• Use Compute Now on the subscription’s Usages tab to preview aggregation results against known test data

3. Validate Pricing & Invoicing

• Verify included quantities (addon price quantity field) are correctly set
• Verify overage rates (addon price price field) match your pricing model
• Simulate a billing cycle and review the generated invoice:
  • Are usage line items present for each UBB-configured addon price?
  • Do raw quantities match expected aggregation?
  • Are included quantities correctly subtracted?
  • Are overage charges calculated correctly?
  • Does the invoice total include both base fees and usage charges?

4. Validate Edge Cases

• Zero usage — Confirm no overage charges when usage is below or equal to included quantity
• No included quantity (PAYG) — Confirm all usage is billed from the first unit
• Multiple UBB addon prices — Confirm each produces a separate invoice line item
• Mid-term cancellation — Confirm usage is billed only through the cancellation date
• Large volumes — Test with realistic event volumes to confirm performance

Using Compute Now

The Compute Now button on the subscription’s Usages tab lets you trigger on-demand aggregation without waiting for the billing cycle:

1. Set up a test subscription with UBB-configured addon prices
2. Ingest test usage events
3. Navigate to the subscription detail page > Usages tab
4. Click Compute Now in the Usage Summary section
5. Review the aggregation results — raw usage, included, billable, and estimated amount per addon price

This is the fastest way to validate your UBB configuration end-to-end.

Time Machine

BillHive provides a Time Machine feature that allows you to simulate billing period transitions without waiting for actual billing cycles. This is the recommended way to test usage-based billing through to invoice generation.

How to use Time Machine:

1. Set up a test subscription with UBB-configured addon prices
2. Ingest test usage events
3. Activate Time Machine to advance the billing period
4. Review the generated invoice

Important: Time Machine clears existing subscriptions and customer data upon activation. Use it only in sandbox or test environments.

End-to-End Lifecycle Test

This section walks through a complete usage-based billing lifecycle test — from subscription creation through renewal to invoice verification. Follow these steps to validate that metered usage charges flow correctly through the entire system.

Step 1: Create a Subscription with a UBB Addon

1. Create (or use an existing) addon price with Per Unit Pricing
2. Configure the UBB fields:
   • Event Type: e.g., api_call
   • Aggregation Method: e.g., COUNT
   • Filters: optional (e.g., {"environment": "production"})
3. Set Quantity (included) and Price (overage rate)
4. Create a subscription for a test customer that includes this UBB-configured addon price

Step 2: Ingest Usage Events

Send usage events via the API that match the addon price’s event type and filters:

POST /usage-events
{
  "event_id": "evt-test-001",
  "event_type": "api_call",
  "subscription_id": "<subscription-id>",
  "customer_id": "<customer-id>",
  "properties": { "environment": "production" },
  "timestamp": "2026-03-01T12:00:00Z"
}

Send enough events to exceed the included quantity so overage charges are generated.

Step 3: Trigger Renewal

Use one of the following methods to trigger the subscription renewal:

• Time Machine — Activate Time Machine to advance the billing period past the term end date. This triggers the renewal workflow including usage aggregation.
• Wait for natural renewal — If testing in a sandbox with short billing periods, wait for the billing cycle to end naturally.

Step 4: Verify Renewal Order Contains Usage Addon Items

After renewal completes, inspect the renewal order:

• Order contains standard recurring line items (base plan, recurring addons)
• Order contains Addon line items with a “Usage” badge for each UBB addon with billable usage
• Each usage addon item shows the correct quantity (billable/overage quantity) and amount
• The item’s options metadata includes aggregation details (raw quantity, included quantity, event type)

Step 5: Verify Invoice Has Usage Line Items

Navigate to the generated invoice for the renewal order:

• Invoice includes usage line items corresponding to the usage addon order items
• Line item amounts match the computed overage charges
• Invoice total includes both recurring fees and metered usage charges

Step 6: Verify Aggregation Records

Check the usage aggregation records for the subscription’s completed billing period:

• Each UBB-configured addon price has an aggregation record
• status = BILLED (not COMPUTED — confirms the order was created successfully)
• order_id is populated and references the correct renewal order
• raw_quantity, included_quantity, billable_quantity, and amount values are correct
• billing_period_start and billing_period_end match the completed term

Expected Outcome

If all checks pass, the full usage-based billing lifecycle is working correctly: events are ingested, aggregated at renewal, included in the order as usage addon items, invoiced, and the aggregation records are updated with the order reference and BILLED status.

Sandbox Environment

For comprehensive testing, use the BillHive sandbox environment where you can:

• Ingest test events without affecting production data
• Create test subscriptions with usage-based pricing
• Simulate full billing cycles
• Review invoices and aggregation records
• Iterate on addon price UBB configurations

Monitoring in Production

After going live, monitor usage-based billing health through:

Troubleshooting