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`.