Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Test Clocks Test 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.

Endpoints

The Test Clock object Test 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

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • 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": "clock_1Mr3I22eZvKYlo2Ck0rgMqd7",
  "object": "test_helpers.test_clock",
  "created": 1680112806,
  "deletes_after": 1680717606,
  "frozen_time": 1577836800,
  "livemode": false,
  "name": null,
  "status": "ready"
}

Create a test clock Test 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.

Returns

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

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

Retrieve a test clock Test helper

Retrieves a test clock.

Parameters

No parameters.

Returns

Returns the TestClock object. Otherwise, this call raises an error.

GET /v1/test_helpers/test_clocks/:id
curl https://api.stripe.com/v1/test_helpers/test_clocks/clock_1Mr3I22eZvKYlo2Ck0rgMqd7 \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "id": "clock_1Mr3I22eZvKYlo2Ck0rgMqd7",
  "object": "test_helpers.test_clock",
  "created": 1680112806,
  "deletes_after": 1680717606,
  "frozen_time": 1577836800,
  "livemode": false,
  "name": null,
  "status": "ready"
}

List all test clocks Test helper

Returns a list of your test clocks.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit test clocks, starting after starting_after. Each entry in the array is a separate test clock object. If no more test clocks are available, the resulting array will be empty.

GET /v1/test_helpers/test_clocks
curl -G https://api.stripe.com/v1/test_helpers/test_clocks \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/test_helpers/test_clocks",
  "has_more": false,
  "data": [
    {
      "id": "clock_1Mr3I22eZvKYlo2Ck0rgMqd7",
      "object": "test_helpers.test_clock",
      "created": 1680112806,
      "deletes_after": 1680717606,
      "frozen_time": 1577836800,
      "livemode": false,
      "name": null,
      "status": "ready"
    }
  ]
}