Before you begin
- A sandbox API key (
sk_test_...) that belongs to an organization owner or admin. The reset in step 1 needs that role. See API keys. - Your merchant ID (
org_...). curlandjq.
Set your key and IDs
PRODUCT_ID, for the steps after it.
1. Reset the account
Start from an empty account, so a second run builds the same data as the first:Reset the sandbox account
204 No Content means every delete is done or scheduled. A 502 Bad Gateway means the reset is incomplete: call it again with the same body.
Send no usage events while the reset runs: an event that arrives during the reset can survive it. Usage events finish deleting in the background, and the API doesn’t report when that’s done. The steps below create a new customer, so events left from before the reset don’t count for it. If you set an externalId on your customers, wait a few minutes before you create a customer with an externalId you used before the reset.
To keep a catalog you already built, send "keepCatalog": true and skip step 2. See Resetting sandbox data.
2. Create the catalog
Create the catalog in dependency order: product, billable metric, feature, fee, prices, then the plan.Product
calls value of each api.call event, so one event can report a batch of calls. Aggregation values are uppercase.
Billable metric
Metered feature
billableMetricId, and the allowance with the feature’s entitlement template. isSoftLimit: true keeps the customer’s access past 10,000 calls and bills the calls above it. Total usage picks the band on the ladder, and only the calls above the allowance are billed. See Volume (tiered ladder).
Usage price
Fee and fee price
Plan
3. Create a customer
Customer
zipCode. An address field with another name is dropped without an error.
4. Create a test clock
A test clock lets a subscription start in the past and bill its periods as you move the clock forward. Start it on the first day of the month two months ago. The examples use 1 September 2026.Test clock
5. Subscribe and activate
Create the subscription on the clock, starting at the clock’s time:Subscription
pending_payment. In the sandbox, activate it by recording Invoice 0 as paid outside Paygentic:
Record Invoice 0 as paid
status is active before you send usage:
Check the subscription
6. Send usage and advance the clock
For each month, send usage dated at the clock’s current time, then advance the clock one month. Usage counts once the clock moves past it. This loop sends 12 events of 1,000 calls each, 12,000 calls in all. That is 2,000 calls above the allowance.Send one month of usage
202. The idempotencyKey is built from the clock’s time and the loop counter, so if you run the loop twice for the same month, the second run doesn’t count the calls again.
Check the meter before you advance the clock. Usage events are processed in the background, and the meter shows them once they are counted, usually within a minute. For the first month, it should show 12000:
Check the meter
Advance the clock
CLOSING. If you advance again before then, the two months share one invoice.
Wait for the month's invoice
sequenceNumber, because the list isn’t guaranteed to be in any order: 1 for the first month, 2 for the second. Repeat this step for the second month. To see the second band of the ladder, send 60 events instead of 12: 60,000 calls select the 0.001 band, and the 50,000 calls above the allowance are billed at that rate. In the meter check, use 2026-10-01 to 2026-11-01.
After the last month, finish the last invoice. A CLOSING invoice waits 12 hours of clock time for late usage, until its gracePeriodEnd, before Paygentic issues it. The earlier invoices pass that point when you advance the clock for the next month. For the last one, read its gracePeriodEnd and advance the clock past it:
Finish the last invoice
7. Read the invoices
List the invoices
periodStart and periodEnd span two months. With the usage in step 6, you get these invoices:
To see an invoice’s lines, call
GET /v2/invoices/lineItems?invoiceId={id}. To record an invoice as paid, use the same call as for Invoice 0. See Invoices.
8. Track a cost
A cost records what serving the customer costs you. It reads the same usage events as a billable metric with the sameeventType, including events you sent before you created the cost, so you can add it at any point. This one costs $0.0004 per call.
Cost
totalQuantity of 72000 and a totalCost of 28.8:
Cost summary
COUNT would count the 72 events, not the 72,000 calls.
- Use
SUMorCOUNTfor a cost you want to total. A summary withoutsubjectis computed over every customer’s events together, so for other aggregations it isn’t a sum of each customer’s cost. - Revenue and cost are not matched by billing period. Compare them over a range of months, not a single invoice.
9. Check the result
The meter shows what Paygentic counted for a customer over any time range:Usage counted for the customer
72000. Compare it with the usage lines on the invoices.
To see the allowance, find the customer’s entitlement with GET /v1/entitlements?customerId={id}, then read its balance with GET /v1/entitlements/{entitlementId}. With the clock in November and no November usage, balance is 10000. Read a balance only after the meter shows all the usage for the period.
Make it re-runnable
A setup you can run again is easier to fix than one you repair by hand. Put the steps in one script:- Start each run with a reset, as in step 1. If you keep the catalog instead, give each resource a fixed name and look for it before you create it.
- List with
limit=100. List endpoints return 10 items by default, so a search withoutlimitcan miss a resource that exists and create a second one. - Save the IDs to a file as you create them, so a later run, or another tool, can read them.
- Follow the dependency order of this page.
- Stop at the first error. A failed create leaves an empty ID, and every later call that uses it fails with a less useful message.
PAYGENTIC_API, PAYGENTIC_KEY and MERCHANT_ID first, and change START and MONTHS to your own dates. It takes about five minutes, most of it spent waiting for the meter and the invoices.
setup-sandbox.sh
99.00, 103.00 and 149.00), the meter total (72000) and the cost (72000 calls, 28.8).
Cautions
- Usage dated before the allowance starts never counts. The allowance measures usage from the subscription’s start or from the moment you created it, whichever is later, and on a test clock that moment is the clock’s time. Send usage dated at the clock’s time. See Usage dated in the past.
- Unknown query parameters are ignored. A misspelt filter returns an unfiltered list with
200 OK, not an error. Check a filtered list’s results before you rely on them. - Error messages say what was refused, not always why. When a call fails, check the request against this page and the endpoint’s page in the API reference.