---
title: "Advance the sandbox Product clock"
method: POST
path: "/v1/sandbox/clock/advance"
tags: ["Sandbox"]
---

# Advance the sandbox Product clock

`POST /v1/sandbox/clock/advance`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/sandbox/clock/advance`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Advances the sandbox clock of the Product bound to the key, or productId named by an authorised tenant session. A key cannot name another Product. Due actions, deadlines and allocation earning read this instant. An unused Product may set its first clock instant in the past, at most 18 calendar months before tenant creation. Business objects, instrument events and money movements prevent a past start. Once set, at only moves the clock forward. Send release instead of at to return the clock to wall time at any point, including from ahead of it; records stamped while the clock ran ahead keep their stamps. Before it responds, the advance runs every clock action that is now due, counts them in ranCount and lists the first 2000 in ran: the record and its title, the customer, the action and the same action in the program's words, its due instant, succeeded or refused, the amount it moves, and for a refusal the reason and, when it is an unfunded charge, that it retries and the account, the amount it needed and the shortfall. Each advance first retries every unfunded charge refused before it, oldest first, and the maintenance sweep retries one about once a minute. Any other refusal is lasting: it carries no retries, stays refused until an action on its record or a write to it, and shows as work for the team. A clock action whose action requires a reference in a state, such as a schedule piece before the payer activates the schedule, waits and is not listed; the activation collects it. A due on any other action only makes it runnable, and a passed deadline refuses its action. The receipt records its previous and new instants. Wall time and other Products are unchanged.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'
- `Idempotency-Key` string, required

## Request body

- object
  - `productId` string: Hyperscale product ID
  - `at` string, date-time
  - `release` true

## Response `200`

Success

- SandboxClockAdvanceOutput
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `previousAt` string, date-time, required
  - `at` string, date-time, required
  - `ran` object[]
    - `instanceId` string, required
    - `objectId` string
    - `instrument` string, required
    - `action` string, required
    - `line` string: The action in the program's words, such as `pay dues 2 of 12`, or `pay dues #2` for a plan that runs until stopped
    - `record` object: The kind and title of the record the agreement belongs to
      - `kind` string, required
      - `title` string, required
    - `customer` object
      - `id` string, required
      - `name` string, required
    - `dueAt` string, date-time, required
    - `status` 'succeeded' | 'refused', required
    - `amount` object
      - `value` string, required: Non-negative minor-unit integer amount serialized as a string (at most 18 digits)
      - `currency` 'SAR', required
    - `reason` string
    - `retries` true
    - `accountId` string: For an unfunded charge: the paying account to fund, as execute's insufficient_balance names it
    - `required` object: For an unfunded charge: what the move needed
      - `value` string, required: Non-negative minor-unit integer amount serialized as a string (at most 18 digits)
      - `currency` 'SAR', required
    - `shortfall` object: For an unfunded charge: how much more accountId needed when it refused
      - `value` string, required: Non-negative minor-unit integer amount serialized as a string (at most 18 digits)
      - `currency` 'SAR', required
  - `ranCount` integer: How many clock actions the advance ran, including any past the first 2000 listed in ran

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)