Test clocks

A test clock is a sandbox clock that you control. Customers created on a test clock, and their subscriptions, read the clock's frozen_at as the current time instead of real time. Use a test clock to check what your integration does when a trial ends, a renewal charges, or a payment retry runs, without waiting days or weeks for it to happen.

Test clocks exist only in sandboxes. Every test clock route needs a test-mode credential: a live credential gets 403 FORBIDDEN with details[0].reason test_mode_required, whatever scopes it holds. Listing and retrieving clocks requires developer.test_clocks.read or developer.test_clocks.write. Creating and archiving them requires developer.test_clocks.write. Both scopes can be granted to live keys, so a live key can grant them to the sandbox keys it creates, but the routes themselves only accept test credentials.

Create a test clock#

POST /v1/test-clocks creates a clock with status ready, stopped at frozen_at. Both fields are optional.

curl -X POST https://api.withflintpay.com/v1/test-clocks \
  -H "Authorization: Bearer flint_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frozen_at": "2026-11-01T00:00:00Z",
    "name": "Annual renewal test"
  }'

frozen_at defaults to the time of the request. Fractional seconds are dropped. It can be up to 5 years after the request time, and no more than 1 hour before it, to allow for clock skew on your side. A value outside that range returns 400 INVALID_REQUEST with param: "frozen_at". name is your label, from 1 to 255 characters.

A new clock has version 1 and sends test_clock.created. There's no limit on the number of clocks in a sandbox.

List and retrieve test clocks#

curl "https://api.withflintpay.com/v1/test-clocks?status=ready&status=archived" \
  -H "Authorization: Bearer flint_test_YOUR_KEY"

GET /v1/test-clocks returns the sandbox's clocks, newest first, then by test_clock_id descending. Set page_size from 1 to 100, with 20 by default, and pass next_page_token as the next request's page_token. Archived clocks are left out unless the status filter names archived. Repeat status, or send comma-separated values, to match several statuses.

curl https://api.withflintpay.com/v1/test-clocks/tclk_01K8ABCDEF0123456789ABCDEF \
  -H "Authorization: Bearer flint_test_YOUR_KEY"

GET /v1/test-clocks/{test_clock_id} returns a clock in this sandbox, including an archived one. A clock in another sandbox returns 404 RESOURCE_NOT_FOUND with param: "test_clock_id", the same as an unknown ID.

Archive a test clock#

curl -X DELETE "https://api.withflintpay.com/v1/test-clocks/tclk_01K8ABCDEF0123456789ABCDEF?expected_version=1" \
  -H "Authorization: Bearer flint_test_YOUR_KEY"

DELETE /v1/test-clocks/{test_clock_id} archives the clock and returns it with status archived. The clock stays readable by ID, never advances again, and no new customer can be created on it. Customers and subscriptions already on it don't change: they keep the clock's frozen_at as their current time, so their subscriptions don't bill again. Cancel those subscriptions first if you want them canceled, or reset the sandbox to remove everything.

expected_version is optional. If it doesn't match the clock's version, the request returns 409 VERSION_CONFLICT with the current version and changes nothing.

The test clock resource#

Statuses#

status is a closed set. Branch on it to decide whether to wait, continue, or start over with a new clock.

Events#

Each event carries the clock as data.object. Events go to the sandbox's webhook endpoints, like any other sandbox event.

What follows the clock#

Customers created on a test clock, their subscriptions, and those subscriptions' payment retries use the clock's time wherever Flint decides or records a point in their billing lifecycle. Everything else uses real time.

Sandbox emails go to real addresses, and webhooks are real sandbox deliveries, so expect them when billing runs on a clock.

Resetting the sandbox removes its test clocks with the rest of its data.