Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Test ClocksTest helper

A test clock enables deterministic control over objects in testmode. With a test clock, you can create objects at a frozen time in the past or future, and advance to a specific future time to observe webhooks and state changes. After the clock advances, you can either validate the current state of your scenario (and test your assumptions), change the current state of your scenario (and test more complex scenarios), or keep advancing forward in time.

Was this section helpful?YesNo
Create a test clock
POST/v1/test_helpers/test_clocks
Retrieve a test clock
GET/v1/test_helpers/test_clocks/:id
List all test clocks
GET/v1/test_helpers/test_clocks
Delete a test clock
DELETE/v1/test_helpers/test_clocks/:id
Advance a test clock
POST/v1/test_helpers/test_clocks/:id/advance

The Test Clock objectTest helper

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • createdtimestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • deletes_aftertimestamp

    Time at which this clock is scheduled to auto delete.

  • frozen_timetimestamp

    Time at which all objects belonging to this clock are frozen.

  • livemodeboolean

    If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

  • namenullable string

    The custom name supplied at creation.

  • statusenum

    The status of the Test Clock.

    Possible enum values
    advancing

    In the process of advancing time for the test clock objects.

    internal_failure

    Failed to advance time. Future requests to advance time will fail.

    ready

    All test clock objects have advanced to the frozen_time.

  • status_detailsobject

    Details on the current state of the Test Clock.

The Test Clock object
{
  "id": "",
  "object": "test_helpers.test_clock",
  "created": 1680112806,
  "deletes_after": 1680717606,
  "frozen_time": 1577836800,
  "livemode": false,
  "name": null,
  "status": "ready"
}

Create a test clockTest helper

Creates a new test clock that can be attached to new customers and quotes.

Parameters

  • frozen_timetimestampRequired

    The initial frozen time for this test clock.

  • namestring

    The name for this test clock.

    The maximum length is 300 characters.

More parameters

  • customerstring

Returns

The newly created TestClock object is returned upon success. Otherwise, this call raises an error.

curl https://api.stripe.com/v1/test_helpers/test_clocks \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d frozen_time=1577836800
Response
{
  "id": "",
  "object": "test_helpers.test_clock",
  "created": 1680112806,
  "deletes_after": 1680717606,
  "frozen_time": 1577836800,
  "livemode": false,
  "name": null,
  "status": "ready"
}