# 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.

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-Key` optional
- **Modes:** Test mode only
- **Authentication:** API key with the `subscriptions:write` scope
- **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

```http
DELETE /api/v1/test_clocks/clk_01jacq4m3xf0v8w9zq2y7k5n6h
Authorization: Bearer or_test_…
```

Response (`200`):

```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                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`test_clock_advancing`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).