Stripe: Create a test clock

← Test helpers operations · Get started

Operation stripe.posttesthelperstestclocks

Provider route: POST /v1/test_helpers/test_clocks. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["testHelpers"]["postTestHelpersTestClocks"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.testHelpers.postTestHelpersTestClocks(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.test_helpers.post_test_helpers_test_clocks(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.customer	string	Optional	Existing customer this test clock will be attached to. Once attached, customers can’t be removed from a test clock. Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.frozen_time	integer	Required within parent	The initial frozen time for this test clock. Format: unix-time
body.name	string	Optional	The name for this test clock. Maximum length: 300

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a test clock — response body

Referenced models: Create a test clock — response body

Schemas

Create a test clock — response body

Field	Type	Presence	Description and constraints
$	object	Root	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.
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
deletes_after	JSON	Required within parent
deletes_after (anyOf 1)	integer	Alternative	Time at which this clock is scheduled to auto delete. Format: unix-time
deletes_after (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
frozen_time	JSON	Required within parent
frozen_time (anyOf 1)	integer	Alternative	Time at which all objects belonging to this clock are frozen. Format: unix-time
frozen_time (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
name	JSON	Optional
name (anyOf 1)	string	Alternative	The custom name supplied at creation. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: test_helpers.test_clock
status	string	Required within parent	The status of the Test Clock. Known values: advancing, internal_failure, ready
status_details	Model	Required within parent	Expand Create a test clock — response body — status details

Referenced models: Create a test clock — response body — status details

Create a test clock — response body — status details

Field	Type	Presence	Description and constraints
$	object	Root
advancing	Model	Optional	Expand Create a test clock — response body — status details advancing

Referenced models: Create a test clock — response body — status details advancing

Create a test clock — response body — status details advancing

Field	Type	Presence	Description and constraints
$	object	Root
target_frozen_time	JSON	Required within parent
target_frozen_time (anyOf 1)	integer	Alternative	The `frozen_time` that the Test Clock is advancing towards. Format: unix-time
target_frozen_time (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Policy, approvals and errors

SDK function policy ID: stripe.posttesthelperstestclocks. Catalog operation: PostTestHelpersTestClocks. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source