Create a test clock · Ownrecord docs

Creates a test clock (test mode only): a time of its own that customers can be attached to when they are created (customers.create with testClockId). Their subscriptions then bill at the clock's time: renewals, trial ends, cancellations and notices happen when you advance the clock (test_clocks.advance), not when real time passes. Use it to test billing scenarios end to end in seconds.

frozenTime is the clock's starting time (default: now), within a year back and five years ahead. A clock holds at most 10 customers. Emits test_clock.created.

At a glance

REST: POST /api/v1/test_clocks
MCP tool: test_clocks_create
Operation ID: test_clocks.create
Scope: Brand
Permission: subscriptions:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test mode only
Authentication: API key with the subscriptions:write scope
Since: M5

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`name`	string	Yes	A name for the clock, e.g. the scenario it tests.
`frozenTime`	date-time	No	The clock's starting time (default: now), within a year back and five years ahead.

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`clk_…` ID
`object`	`"test_clock"`
`livemode`	`false`
`brandId`	`brd_…` ID
`name`	string
`frozenTime`	date-time	The clock's time: its customers' subscriptions bill as if it were now.
`status`	one of `ready`, `advancing`, `internal_failure`	`ready`, `advancing` (an advance runs: wait for `ready`) or `internal_failure` (the last advance stopped on an error, see `advance.error`; advance again).
`advance`	object or null	The latest advance.
`version`	integer
`createdAt`	date-time
`updatedAt`	date-time

Examples

A clock starting now

HTTP

POST /api/v1/test_clocks
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "name": "Monthly renewal",
  "frozenTime": "2026-10-20T09:00:00.000Z"
}

Response (201):

JSON

{
  "id": "clk_01jacq4m3xf0v8w9zq2y7k5n6h",
  "object": "test_clock",
  "livemode": false,
  "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6b",
  "name": "Monthly renewal",
  "frozenTime": "2026-10-20T09:00:00.000Z",
  "status": "ready",
  "advance": null,
  "version": 1,
  "createdAt": "2026-10-20T09:00:00.000Z",
  "updatedAt": "2026-10-20T09:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The name is empty or too long, or `frozenTime` is out of range.	Fix the fields listed in `details.issues` and send the request again.
`mode_not_supported`	400	The request is in live mode: test clocks exist in test mode only.	Use the mode the operation supports (`details.supported_mode`): test-only operations such as test clocks need test-mode credentials.
`permission_denied`	403	The credentials can't manage this brand's subscriptions (`subscriptions:write`).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

A clock starting now#

Errors#