# API and advanced usage Learn advanced strategies for using test clocks in the Dashboard and API. You can run a simulation separately from a subscription for running advanced simulations. In this scenario, you create the simulation first and then add different test cases to it. Not ready for a full integration? See [our guide](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md) for running simulations on subscriptions. Follow these steps to start using test clocks: 1. [Create a simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Set up your simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Advance time](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Monitor and handle the changes](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Update the simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) 1. [Delete the simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#delete-clock) You can advance the time, monitor changes, and update the simulation as often as you need to test different cases. ## Create a simulation and set its time A simulation uses a clock as its object, letting you reference the clock’s time. To start a simulation, create a clock and set its frozen time—the starting point for your tests. Set the frozen time to a point in the past or future, but after you set it, you can only move it forward in time. #### Dashboard [Create a sandbox](https://docs.stripe.com/sandboxes/dashboard/manage.md) to start simulating. 1. Go to the **Subscriptions** [section](https://dashboard.stripe.com/test/subscriptions) under the **Billing** tab. 1. Click [Simulations](https://dashboard.stripe.com/test/test-clocks) link in the banner. 1. Click **New simulation**. 1. In the **Create new simulation** modal, enter a name for the simulation. You can use this to describe the simulation you’re testing, like `Annual renewal` or `Free trial`. 1. Set the frozen time for the simulation. #### API With the API, you specify the time in the [frozen_time](https://docs.stripe.com/api/test_clocks/object.md#test_clock_object-frozen_time) field as a Unix Epoch timestamp. This example sets the frozen time of the `Annual renewal` clock to November 1, 2021 7:00:00 AM GMT (`1635750000` in Unix Epoch format). ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1635750000 \ -d "name=Annual renewal" ``` Note the `id` of the created test clock (for example, `clock_1JGWQvIyEfDZOm8cxyhPwsoc`). You’ll use it to create a customer and advance the time. ## Set up your simulation Next, set up the test case for your simulation. You need to create a customer first, then a subscription for them. #### Dashboard To create a customer for your simulation through the Dashboard: 1. Go to the [Simulations](https://dashboard.stripe.com/test/test-clocks) page and find your simulation. 1. Click **Add** > **Add customer**. You can’t choose existing customers during simulations. You can add up to three new customers to each simulation. You can optionally enter other available properties for the customer, like their name, email, and billing information, but none are required. For some simulations, like testing free trials, you might not want to collect any billing information up front. Next, you can create up to three subscriptions or subscription schedules for your customer. To create a subscription for the customer through the Dashboard: 1. Go to the [Simulations](https://dashboard.stripe.com/test/test-clocks) page and find the simulation. 1. Click **Add** > **Add subscription**. Select or search for your customer from the drop-down menu. You can also add the customer to a subscription through the customer page, by clicking **Actions** > **Create subscription**. 1. Select a recurring product and price in the **Pricing** section. 1. For the **Subscription schedule**, define the start and end date for the subscription and when to start the billing period. 1. Choose a payment collection method: - Select **Automatically charge a payment method on file** if you want to charge your customer when the billing period starts. - Select **Email invoice to the customer to pay manually** if you want to invoice your customer in arrears. 1. Click **Start test subscription** to start the subscription and billing period. #### API If your Connect platform uses [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), use our [guide](https://docs.stripe.com/connect/use-accounts-as-customers.md) to replace `Customer` and event references in your code with the equivalent Accounts v2 API references. Use the following code sample to create a Customer and associate it with the clock. Remember to set a [default payment method](https://docs.stripe.com/api/customers/create.md#create_customer-payment_method) for the customer (unless you want to test a free trial or similar simulation). You can use a [test card](https://docs.stripe.com/testing.md#cards) for this. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_card_visa \ -d "invoice_settings[default_payment_method]=pm_card_visa" ``` By default, the [List all customers](https://docs.stripe.com/api/customers/list.md) endpoint doesn’t include customers with test clocks. You can use the [test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock) parameter to get a list of all customers that are attached to the specified test clock. Use the customer you created to [create a new Subscription](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). The subscription is associated with the clock through the customer, so you don’t have to pass the clock ID to create the subscription. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` Both the customer and subscription are associated with the simulation you created in the [first step](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock). ## Advance the simulated time After you’ve created a simulation and set up your test case, advance the simulated time. The first time you do this, you’ll advance the time from the initial frozen time you set at the start. As you advance time, you can see how your integration works when subscriptions end, renew, or undergo other changes (like upgrading from a free trial to a paid subscription). Advance time in intervals of up to two. The length of the interval is based on the shortest service period associated with the subscription, which is determined by the recurring price. For example, if you have a monthly subscription, you can only advance up to two months at a time. If you haven’t set any subscriptions or subscription schedules, you can advance up to two years from the initial frozen time. #### Dashboard To advance time through the Dashboard: 1. Go to the [Simulations](https://dashboard.stripe.com/test/test-clocks) page and find your simulation. 1. Click **Advance time**. 1. Use the calendar modal to select the date you want to advance the clock to. 1. Click **Advance**. #### API To advance time through the API, update the `frozen_time` parameter. For example, to advance it to November 1, 2022 to test an annual renewal: ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1667286000 ``` ## Monitor and handle changes After a successful API request or Dashboard operation, it takes a few seconds to advance to the specified time. To know when the simulation has changed status, you can use webhooks to listen for event notifications or you can poll the clock object. The Dashboard also reflects the changes. For example, you can go to the [Invoices page](https://dashboard.stripe.com/test/invoices) to check whether an invoice was created or paid for your subscription. If you use [webhooks](https://docs.stripe.com/webhooks.md), listen to the following event notifications. Before production, make sure your integration correctly handles the other [billing-specific event notifications](https://docs.stripe.com/billing/subscriptions/webhooks.md) in addition to the ones listed below. | Event | Description | | ----------------------------------- | ----------------------------------------------------------------------- | | `test_helpers.test_clock.advancing` | The clock has started to advance but hasn’t reached the specified time. | | `test_helpers.test_clock.ready` | The clock has completed advancing to the specified time. | To poll the status of the clock, [retrieve](https://docs.stripe.com/api/test_clocks/retrieve.md) it by ID to examine its `status`. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` ## Update the simulation You can continue to make changes to your simulation and [advance the clock](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) for simulations like: - Adding a [customer balance](https://docs.stripe.com/billing/customer/balance.md). - Making a mid-cycle upgrade. - [Adding one-off invoice items](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). After each update, [monitor the changes](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) again. Repeat as many times as you need to satisfy your test case. ## Delete a simulation Simulations are automatically deleted 30 days after you create them, but you can delete them when you’re done testing to ensure a clean test environment. #### Dashboard To delete a simulation and all of its associated test objects through the Dashboard: 1. Go to the [simulations](https://dashboard.stripe.com/test/test-clocks) page and find your simulation. 1. Click **Finish simulation**. 1. In the confirmation modal, click **Finish**. #### API To delete the clock and all of its associated test objects through the API: ```curl curl -X DELETE https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` Deleting the simulation also deletes the test customers associated with the clock and cancels their subscriptions. Simulations are only available in sandboxes, so you can’t delete any production objects when you delete a clock. ## Use cases In each case, begin by creating a new simulation: 1. [Create a simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Set up your simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Advance time](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Monitor and handle the changes](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Update the simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) ### Test subscription renewals Let’s say that you’d like to test that a 50 USD/month subscription renews correctly: - Create a simulation and set its `frozen_time` to January 1. - Add a customer and add a payment method for the customer: #### Dashboard To add a payment method for a customer in the Dashboard: 1. From the customer account page, click **Add > Add card** from the **Payment methods** section. 1. Enter payment information. In this case, use the 4242424242424242 [test card](https://docs.stripe.com/testing.md#cards). 1. Click **Add card** in the modal. #### API To set a [default payment method](https://docs.stripe.com/api/customers/create.md#create_customer-payment_method) for the customer: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_card_visa \ -d "invoice_settings[default_payment_method]=pm_card_visa" ``` - After adding a payment method for the customer, create a subscription for the new customer set at 50 USD/month. In doing so, the invoice of 50 USD is paid automatically and the subscription is `active`. - Advance the date to February 1 to see that an invoice of 50 USD is created. By default, the invoice appears in a `draft` status for [one hour](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items). - Advance the time by one hour to see that the invoice is finalized and paid automatically. ### Test mid-cycle upgrades with prorations Let’s say that you have two products. One product is 50 USD month (basic plan), and the other is 100 USD month ('premium plan). In this case, you might want to test prorations for a customer who upgrades their basic plan to the premium plan in the middle of a billing period. To simulate this: - Create a simulation and set the `frozen_time` to January 1. - Create a customer and add their payment method. In this case, use the 4242424242424242 [test card](https://docs.stripe.com/testing.md#cards). - Create a subscription for the ‘basic plan’ at 50 USD/month. After this is done, you’ll see that the 50 USD/month invoice is created, finalized, and automatically paid. - Advance the date by two weeks. In this case, we’ll set the date to January 16. - Upgrade the subscription to a ‘premium plan’ at 100 USD/month: #### Dashboard To upgrade a subscription using the Dashboard: 1. From the customer account page or the subscription details page, click the overflow menu (⋯) associated with a subscription, then select **Update subscription**. 1. Make your desired modifications. 1. Click **Update subscription** in the top right corner to apply the changes. #### API You can use pending updates with the [update subscription](https://docs.stripe.com/api/subscriptions/update.md), [create subscription item](https://docs.stripe.com/api/subscription_items/create.md), and [update subscription item](https://docs.stripe.com/api/subscription_items/update.md) calls. When you make the update, set `payment_behavior=pending_if_incomplete`. The example below adds a new price to a subscription. Because `proration_behavior=always_invoice`, an invoice is created and payment is attempted when the update is made. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` - After upgrading the subscription, the [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) webhook event is created. - Pending invoice items are also created for the prorations. You’ll see a negative proration of -25 USD for the unused time with the ‘basic plan’ and a positive proration of 50 USD for using the ‘premium plan’ for half of the remaining month. At this point, no invoice has been generated. - Advance the date by two weeks. In this case, set the date to February 1. You’ll see that the subscription has cycled. An invoice has been generated in a `draft` status and has incorporated the pending invoice items, including a negative proration, a positive proration, and the total payment for the month of February, resulting in 125 USD. By default, the invoice appears in a `draft` status for approximately [one hour](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items). - To finalize the invoice, advance the time by one hour. ### Test trials Let’s say that you want customers to try your product for free with a seven-day trial before they start paying and want to collect payment information up front. To simulate this situation using test clocks, follow these steps: - Create a new simulation and set the `frozen_time` to January 1. - Add a customer and include their payment method. In this case, use a 4242424242424242 [test card](https://docs.stripe.com/testing.md#cards). - Create a subscription and add a seven-day free trial period: #### Dashboard To add a trial period to an existing subscription using the Dashboard: Find the subscription you want to change. 1. Click **Actions**. 1. Click **Update subscription**. 1. Click **Add free trial** and enter seven in **Free trial days** field. 1. Click **Update subscription**. #### API You can start a customer’s subscription with a free trial period by providing a `trial_period_days=7` argument when creating the subscription: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` - After creating a subscription with a seven-day free trial period, a subscription is created in a `trialing` status. An invoice of 0.00 USD is generated due to the free trial. - Advance the date to January 5 to see the [customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.trial_will_end) event notification. Stripe sends the notification three days before the trial ends. You can use this webhook event to inform your customers that the trial ends soon. - Advance the date to January 8 to see that the subscription is now `paid` and an invoice for 50 USD is created. - Advance the date by one cycle (for example, to February 8 for a monthly subscription) to see the subscription renew successfully. ## Limitations You can simulate up to: - Three customers - Three subscriptions, including [scheduled subscriptions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md), per customer - Ten quotes that aren’t attached to customers ### Test clock objects omitted in list all results Stripe list APIs (such as [List invoices](https://docs.stripe.com/api/invoices/list.md)) omit results generated by test clocks for list all requests. To see results generated by test clocks in these cases, you must request results within a specific parent, such as `test_clock`, `customer`, or `subscription`. For example, `GET /v1/invoices` won’t return test clock generated invoices, but `GET /v1/invoices/{customer_id}` returns all invoices for that customer, including those that are test clock generated. Similarly, you can specify a test clock ID in this example to get all invoices related to that test clock, or you can specify a subscription ID to return all invoices billed for that subscription, including test clock generated invoices. ### Rate limit errors If you make multiple updates to a subscription that has a test clock, Stripe might return a rate limit error. Since the subscription is frozen to the time of the test clock, all API requests count toward that time, which can trigger the rate limit. To avoid this, advance the simulated time of the clock by a few minutes before making additional API requests on the subscription. The Subscriptions API restricts the maximum number of requests as follows: - 10 new invoices per subscription, per minute - 20 new invoices per subscription, per day - 200 quantity updates per subscription, per hour ### Caveats with payment processing Test clock advancement currently doesn’t support collecting payments through bank debits (for example, `us_bank_account` payment method types). Stripe collects payments after the test clock advances. To test payment failures: 1. Choose the **Cancel subscription after all payment retries fail** setting. 1. Attach a `us_bank_account` payment method type to a customer that fails payments. 1. Create a subscription under the customer. 1. Advance the test clock to cycle and collect payment on a subscription. After the Test Clock advances, the subscription remains in the `active` status. This indicates that the payment collection wasn’t attempted during test clock advancement, and the subscription hasn’t entered the `canceled` status due to `payment_failed`. Listen to the `invoice.payment_failed` event to monitor the delayed subscription status and invoice payment. The `customer.subscription.deleted` event indicates that the subscription status is set to `canceled`.