Skip to content

BillKit/DocsConsole

Test clocks

Create test clock

Create a test clock, frozen at frozen_time, to test billing over time.

POST/v1/test_clocks

Operation create_test_clock·Scope test_clocks:write·OpenAPI v1.1.0

Parameters

Parameter	Description
frozen_timeintegerrequired	The time the clock starts frozen at, in Unix seconds. At most 4102444800 (2100-01-01). Maximum `4102444800`.
namestring \| nulloptional	A label for the clock. At most 255 characters.

Returns

Returns a TestClockResponse object.

Errors

Status	Cause
400	The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.
401	No credential, or one that does not authenticate.
402	The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).
403	Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin. Needs the `test_clocks:write` scope.
404	No such object in this account and mode.
409	Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).
413	The request body is larger than the API accepts.
429	Rate limited. `Retry-After` says when to try again.
500	Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.
502	The payment provider failed or did not answer.
503	Temporarily unable to serve. `reason` says whether the request was attempted.

List test clocks GET /v1/test_clocks
Delete test clock DELETE /v1/test_clocks/{test_clock_id}
Get test clock GET /v1/test_clocks/{test_clock_id}
Advance test clock POST /v1/test_clocks/{test_clock_id}/advance

Request · curl

curl -X POST https://api.billkit.eu/v1/test_clocks \
  -H "Authorization: Bearer $BILLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frozen_time":1789392000}'

curl -X POST https://api.billkit.eu/v1/test_clocks \
  -H "Authorization: Bearer $BILLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frozen_time":1789392000}'

Request body · every field

{
  "frozen_time": 1789392000,
  "name": "Ada Lovelace"
}

{
  "frozen_time": 1789392000,
  "name": "Ada Lovelace"
}

Response · 200 OK

{
  "created": 1789392000,
  "frozen_time": 1789392000,
  "id": "tc_9XKp2vQ1",
  "livemode": false,
  "name": "Ada Lovelace",
  "object": "test_clock"
}

{
  "created": 1789392000,
  "frozen_time": 1789392000,
  "id": "tc_9XKp2vQ1",
  "livemode": false,
  "name": "Ada Lovelace",
  "object": "test_clock"
}