Sample - Stripe API
POST/v1/test_helpers/test_clocks/{test_clock}/advance

Advance a test clock

Triggers advancement of a test clock to a specified future time. Supply frozen_time after the clock's current frozen time and within the permitted future range; advancement continues until the clock reaches the ready state.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
test_clockstringrequired
The identifier of the test clock to advance. Maximum 5,000 characters.

Form data specifying the future time to which the test clock should advance.

expandarray<string>optional
Specifies which fields in the response should be expanded.
frozen_timeintegerrequired
The time to advance the test clock. Must be after the test clock's current frozen time. Cannot be more than two intervals in the future from the shortest subscription in this test clock. If there are no subscriptions in this test clock, it cannot be more than two years in the future.

2 status codes
200Returns the test clock object with its target advancement in progress or completed, including its current status, frozen time, and status details.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
deletes_afterintegerrequired
Time at which this clock is scheduled to auto delete.
frozen_timeintegerrequired
Time at which all objects belonging to this clock are frozen.
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
namestringoptional
The custom name supplied at creation.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:test_helpers.test_clock
statusstringrequired
The status of the Test Clock.
Allowed:advancinginternal_failureready
status_detailsobjectrequired
defaultError response.
errorobjectrequired

Error handling

frozen_time is required and must be a Unix timestamp after the test clock's current frozen time. The target cannot be more than two subscription intervals ahead of the shortest subscription, or more than two years ahead when the clock has no subscriptions.