Skip to content
Hardcount
Run it locally
Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Create a test clock

POST
/v1/test-clocks
curl --request POST \
  --url http://localhost:8080/v1/test-clocks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "frozen_time": "2026-04-15T12:00:00Z" }'

Test mode only. The clock starts in ready state at frozen_time. Use /advance to move it forward.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
string
<= 200 characters
frozen_time
required
string format: date-time

Example generated

{
  "name": "example",
  "frozen_time": "2026-04-15T12:00:00Z"
}

Responses

Section titled “Responses”

201

Section titled “201”

Clock created

Media typeapplication/json

A clock for test mode. Customers and subscriptions attached to it are billed on its time, not the real time.

object
id
required
string
tenant_id
string
name
required
string
frozen_time
required

The clock’s current time.

string format: date-time
status
required

ready: it can be advanced or deleted. advancing: billing is catching up to the new time. internal_failure: the last advance failed partway; resume it with POST /v1/test-clocks/{id}/retry-advance.

string
Allowed values: ready advancing internal_failure
created_at
required
string format: date-time
updated_at
required
string format: date-time
last_failure_reason

Why the last advance failed. Cleared by the next successful advance.

string
last_advance_summary

What the latest advance did: the time span it covered and how many of each billing step it ran. Absent until the clock is first advanced.

object
advanced_from
required
string format: date-time
advanced_to
required
string format: date-time
invoices_generated
required
integer
trials_activated
required
integer
pauses_resumed
required
integer
thresholds_fired
required
integer
tax_retried
required
integer
charges_retried
required
integer
clawbacks_issued
required
integer
credits_expired
required
integer
dunning_advanced
required
integer
had_errors
required

True when a step failed. The counts then cover only the work done before the failure.

boolean

Example 

{
  "status": "ready"
}