Delete a test clock
The test_clocks.delete operation: DELETE /api/v1/test_clocks/{id} in the REST API and the test_clocks_delete tool in the MCP server.
/api/v1/test_clocks/{id}Deletes a test clock with what it simulated: its customers' live subscriptions are canceled at once at the
clock's time (nothing more is billed or credited), its customers are deleted, and the clock is removed. Invoices
and ledger entries made while it ran stay, as test-mode records. Refused while the clock is advancing. Emits
test_clock.deleted (and subscription.canceled, customer.updated for what it ended).
At a glance
- REST:
DELETE /api/v1/test_clocks/{id} - MCP tool:
test_clocks_delete - Operation ID:
test_clocks.delete - Scope: Brand
- Permission:
subscriptions:write - Risk tier:
write - Dry run: Supported (send
Ownrecord-Dry-Run: true) - Idempotency:
Idempotency-Keyoptional - Modes: Test mode only
- Authentication: API key with the
subscriptions:writescope - Since: M5
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | clk_… ID |
Body
This operation takes no body.
Response
200 OK 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
Delete a clock
DELETE /api/v1/test_clocks/clk_01jacq4m3xf0v8w9zq2y7k5n6h
Authorization: Bearer or_test_…
Response (200):
{
"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 |
|---|---|---|---|
test_clock_advancing | 409 | The clock is advancing: wait until its status is ready. | Wait until the clock's status is ready (read it with test_clocks.get), then try again. An advance processes every due renewal, trial end and cancellation of the clock's subscriptions first. |
resource_not_found | 404 | No test clock with this ID exists for the brand in test mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
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: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.