stripe-test-clock-constraints

name	stripe-test-clock-constraints
description	Reference for Stripe test clock constraints and pitfalls. Use when planning or debugging test-clock workflows, when an advance or customer-attach step fails, or to check rules before building a time-simulation scenario with create_stripe_test_clock, advance_stripe_test_clock, and create_stripe_test_customers.

Stripe Test Clock Constraints

Quick reference for the rules and gotchas of Stripe test clocks as exposed by this MCP. Consult this before designing a time-simulation scenario.

Hard constraints

• Max 3 customers per clock. create_stripe_test_customers with a test_clock set rejects number > 3. To exceed 3 customers in one scenario, use additional clocks.
• Clock attachment is creation-time only. A customer can be linked to a test clock only when it is created (create_stripe_test_customers with test_clock). There is no way to attach or move an existing customer to a clock afterward, so create the clock first.
• Advance is forward-only. advance_stripe_test_clock can only move frozen_time to a time after the current frozen time. You cannot rewind a clock; to test an earlier point, create a new clock.
• Advance is asynchronous. After advance_stripe_test_clock, the clock enters an advancing state and processes billing events in the background. The tool returns the status once in its response, but this MCP server does not expose a tool to retrieve or re-poll the clock, so you cannot programmatically watch it reach ready. If the response shows advancing, wait a few seconds before follow-up operations, or have the user confirm the clock has settled in the Stripe Dashboard.

Time format

• frozen_time is a Unix timestamp in seconds (epoch seconds), not milliseconds and not an ISO string.
• Convert carefully:
  • Many languages give milliseconds (Date.now() in JS) — divide by 1000 and floor.
  • From an ISO date: compute epoch seconds (for example, in shell date -d '2024-02-01T00:00:00Z' +%s).
  • When reading a value back, multiply by 1000 to build a JS Date.
• A common bug is passing milliseconds, which lands the clock far in the future; double-check the magnitude (a 2024-2026 timestamp is ~1.7e9, a millisecond value is ~1.7e12).

Practical guidance

• Plan all the time points you need up front; since you cannot rewind, build a fresh clock per backward scenario.
• Keep the test_clock_id returned at creation; it is required for every advance.
• To cross a billing boundary, advance to just past the subscription's current_period_end.
• For an end-to-end billing procedure, see stripe-billing-cycle-test.
• For setup/cleanup of the data around clocks, see stripe-test-data-lifecycle.