Skip to main content
Time: about 20 minutes · Level: beginner · You’ll build: a simulated customer whose first billing period closes, producing an invoice you can inspect, without waiting a month.

​
Scenario

You’ve set up the plan in Meter your first API. Before you go live, you want to see the first invoice: the usage charges, the date it’s due, and what happens when a payment fails. Waiting a real month is impractical, so you’ll use a test clock.

​
Prerequisites

  • A sandbox workspace. Test clocks only run in sandbox.
  • The cust_tutorial_1 customer and their subscription from the first tutorial.
  • Some usage recorded on that customer.
1

Create a clock at the start of the period

Freeze the clock at the subscription’s start date, so the first period begins now.
frozenTime must include a timezone offset or Z. Use a date before the usage you want to bill.
2

Attach the customer

Attach one customer per request. Only attached customers move with the clock.
The customer must be created in this sandbox. Customers in another workspace or a live workspace can’t be attached.
3

Record usage inside the period

Usage has to be dated inside the period you’re about to close. Send events with timestamps between the clock start and the end of the month:
With a unit price of 0.001,tworequestsbill0.001, two requests bill 0.002 for this period.
4

Advance the clock past the period end

to is required and must be an ISO 8601 timestamp. Move it past the end of the first month:
Advancing the clock processes billing for the attached customer up to that time. That includes the renewal and any invoice due in the interval.
5

Inspect the invoice

Check three things: the total matches your expectation ($0.002 plus any plan fee), the status is open or paid, and the due date falls in the right place.Look at the line items on the invoice before you trust the total. Each usage price should appear as its own line.
6

Simulate a failed payment

To check your retry and notification handling, a payment must fail. Use a test payment method that your payment provider documents as declining, attach it to the customer, then advance the clock again. The decline and any retries are recorded against the invoice:
Watch the webhooks you configured in Receive webhooks securely for invoice.payment_failed, then invoice.payment_recovered or invoice.marked_uncollectible.
Use your payment provider’s published test cards only, and only in sandbox. Real cards are never charged in a sandbox workspace.

​
What to check before launch

  • Usage outside the period is excluded from the invoice.
  • A failed 500 request isn’t billed, if your metric filters on statusCode.
  • The invoice total matches your pricing calculator.
  • Your webhook handler activates and deactivates features on the events above.

​
Next steps

Environments and sandbox

Keep test and live data apart.

Invoicing and collection

The full invoice lifecycle.