# Test your Billing integration

Learn how to test your Billing integration to make sure it's ready for production.

Test how your Billing integration handles subscription renewals, trials, payment failures, and webhook notifications before processing live payments. Choose the tests that apply to your integration and run them in a [sandbox](https://docs.stripe.com/sandboxes.md). For general testing guidance, see [Testing](https://docs.stripe.com/testing.md).

## Testing scenarios 

Review the following scenarios and run the tests that apply to your integration.

> #### Accounts v2 availability
> 
> The customer sign-up test in the following table refers to both `Customer` objects from the v1 API and customer-configured `Account` objects from the [Accounts v2 API](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md). The Accounts v2 API is generally available for Connect users and in public preview for other Stripe users.

| Scenario | What to verify | How to test |
| --- | --- | --- |
| **Customer sign-up** | Your sign-up flow collects the required customer information and stores a customer-configured `Account` or `Customer` object in Stripe. | Complete your integration’s sign-up flow in a sandbox. In the Dashboard, confirm you’re viewing that sandbox, then go to **Customers** and find the customer record. |
| **Invoicing** | *Invoices* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) are generated and payment is collected as expected, either by automatically charging a payment method or sending an invoice to the customer. | [Simulate renewals and billing cycles](https://docs.stripe.com/billing/testing.md#simulate-subscriptions). |
| **Subscription management** | The subscription in Stripe reflects any changes made through the *customer portal* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details). | With your [customer portal configured](https://docs.stripe.com/customer-management/configure-portal.md), create a sandbox subscription, open the customer portal as the test customer, and update the subscription. In the Dashboard, confirm you’re viewing that sandbox, then go to **Subscriptions** and verify the change. |
| **Trials** | The subscription starts in `trialing` status, generates a zero-value trial invoice, and transitions to the expected status when the trial ends. | [Test subscription trial periods](https://docs.stripe.com/billing/testing.md#trials). |
| **Payment failures** | Your integration detects failed payments and handles retries and customer notifications according to your configuration. | [Test payment failures](https://docs.stripe.com/billing/testing.md#payment-failures). |

To identify the webhook events to monitor during these tests, see [Subscription events](https://docs.stripe.com/billing/subscriptions/webhooks.md#events).

## Subscription lifecycle tests

### Test renewals and changes over time 

Use test clocks to advance simulated time in a sandbox and see how your subscriptions and invoices change. For example, test how your integration handles a payment failure at an annual renewal without waiting a year.

You can run simulations in the Dashboard without writing code, or use the API. Use simulations to:

- Test mid-cycle upgrades and plan changes.
- Test how [customer balances](https://docs.stripe.com/billing/customer/balance.md) and [one-off invoice items](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items) affect upcoming invoices.
- Verify that your integration processes Billing lifecycle webhooks correctly.
- Validate your app’s trial handling.
- Build and test multi-phase subscription schedules.

#### Simulate subscriptions 

Follow these steps to simulate a subscription in the Dashboard. To create and manage test clocks through the API, see [Advanced test clock usage](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md).

1. Create a sandbox in the [Dashboard](https://dashboard.stripe.com).

2. On the [Subscriptions](https://dashboard.stripe.com/test/subscriptions) page, click the subscription you want to test.

3. Click **Run simulation** in the banner.

   The Dashboard might disable **Run simulation** if the subscription’s customer:

   - Has more than three subscriptions, including [scheduled subscriptions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md).
   - Has a complex profile with more than 25 quotes, invoices, or other related objects.

4. In the modal, set the date and time to simulate, then click **Advance time**.

   You can advance the clock by any increment, up to two subscription intervals at a time from the initial frozen time. For example, for a monthly subscription, you can advance up to 2 months at a time. When the simulation completes, the banner displays the current simulation time.

#### View and delete simulations

View your simulations in **Subscriptions** > [Simulations](https://dashboard.stripe.com/test/billing/subscriptions/simulations) in the Dashboard.

To delete a simulation, click **Finish simulation**. This deletes all associated objects from the sandbox, including the customer and subscription. It doesn’t affect live mode.

### Test subscription trial periods 

To test a 7-day free trial that collects payment information up front, use test clocks:

1. Create a new simulation and set the `frozen_time` to January 1.

2. Add a customer and include their payment method. In this case, use a 4242424242424242 [test card](https://docs.stripe.com/testing.md#cards).

3. Create a subscription and add a 7 day free trial period:

   #### Dashboard

   To add a trial period to an existing subscription using the Dashboard:

   1. Find the subscription you want to change.
   2. Click **Actions**.
   3. Click **Update subscription**.
   4. Click **Add free trial** and enter seven in **Free trial days**.
   5. Click **Update subscription**.

   #### API

   Create the subscription with `trial_end` set to 7 days after the simulation’s `frozen_time`, replacing the value in this example:

   #### Accounts v2

   ```curl
   curl https://api.stripe.com/v1/subscriptions \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
     -d "items[0][price]={{PRICE_ID}}" \
     -d trial_end=1610403705
   ```

   #### Customers v1

   ```curl
   curl https://api.stripe.com/v1/subscriptions \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "customer={{CUSTOMER_ID}}" \
     -d "items[0][price]={{PRICE_ID}}" \
     -d trial_end=1610403705
   ```

   **Expected result:** The subscription has a `trialing` status and generates a zero-value invoice for the free trial.

4. Advance the date to January 5 to test the [customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.trial_will_end) event notification with the default 3 day notification window. If you’ve configured a different notification window, advance to that point instead. You can use this webhook event to inform your customers that the trial ends soon.

5. Advance the date to January 8 to end the trial. Advance simulated time as needed for invoice finalization and payment collection.

   **Expected result:** With a successful payment, the subscription becomes `active` and the invoice is paid. The subscription’s configured price determines the invoice amount.

6. Advance the date by one cycle (for example, to February 8 for a monthly subscription) to see the subscription renew successfully.

#### Test trial periods without test clocks 

To test trial periods without waiting for a full trial:

1. Create a subscription with a [trial_end](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_end) value a few minutes in the future using the Subscriptions API. If you use Checkout, set [subscription_data.trial_end](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-trial_end) to at least 2 days in the future.
2. Let the trial end, then verify the subscription and invoice statuses expected for your configured payment flow.

Use [test clocks](https://docs.stripe.com/billing/testing.md#test-clocks) for controlled testing of `customer.subscription.trial_will_end` notification timing. Short trials can end before background notification processing observes them.

The default notification window is 3 days before the trial ends.

### Test subscription webhook notifications 

Subscriptions integrations rely on *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). You set up a webhook endpoint on your server and specify which event notifications to listen for. Stripe sends notifications for events such as a subscription upgrades or cancellations. [Verify webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) to confirm that events came from Stripe.

Whether you represent customers with Accounts v2 or [Customer objects](https://docs.stripe.com/api/customers.md), listen for `customer.subscription.*` events to track subscription activity.

Use these two methods to test your integration:

- **Test the subscription flow**: Create actual sandbox subscriptions, perform [subscription lifecycle](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) actions such as upgrades or cancellations, and verify the received events and your application’s behavior.
- **Test individual handlers**: Set up the [Stripe CLI](https://docs.stripe.com/stripe-cli.md) and link it to your Stripe account to trigger synthetic event notifications, or trigger them through the [Dashboard](https://dashboard.stripe.com/test/account/webhooks). These events contain test data that doesn’t correspond to real subscription resources, so they don’t validate the complete subscription lifecycle.

Use the Stripe CLI to receive event notifications on your server without network tunnels or firewalls. Don’t rely on receiving events in a particular order.

For subscription event types and handling guidance, see [Subscription events](https://docs.stripe.com/billing/subscriptions/webhooks.md#events).

## Payment tests

### Test payment failures 

Use [test cards](https://docs.stripe.com/testing.md#cards) to trigger payment failures for subscriptions and invoices.

A failed initial payment can leave a newly created subscription in an `incomplete` status. To test a payment failure after a trial instead:

1. Set 4000000000000341 as the customer’s default payment method.
2. Create a subscription with a short trial to defer the payment attempt until the trial ends.
3. Let the trial end and wait for the invoice to finalize and payment collection to be attempted.

In this test, the payment attempt fails and your integration receives `invoice.payment_failed`. Verify the invoice and subscription statuses, then check that your integration follows your configured retry and customer-notification behavior.

To test a payment failure at a quarterly or annual renewal without waiting for the billing period to pass, use test clocks to advance simulated time in a sandbox. See [advanced test clock scenarios](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#use-cases).

### Test payments that require 3D Secure 

To test authentication for subscriptions and invoices:

1. Use the 4000002760003184 card to trigger 3D Secure.
2. Authenticate or fail the payment attempt in the 3D Secure dialog that opens.

Check the result for each outcome:

- **Successful authentication**: The invoice is paid. If the invoice belongs to a subscription in an `incomplete` status, the subscription becomes `active`.
- **Unsuccessful authentication**: The invoice remains `open`.

For more authentication scenarios, see [3D Secure test cards](https://docs.stripe.com/testing.md#three-ds-cards).

### Test bank transfer payments for invoices 

To test manual payments on invoices through Bank Transfer:

1. In a sandbox, create an invoice and set the collection method to `send_invoice` and set the `payment_settings[payment_method_types]` array to `[customer_balance]`.
2. Find the invoice in the Dashboard and click **Send**.

Stripe allocates your customer a unique virtual bank account number, which you can retrieve through the [funding instructions API](https://docs.stripe.com/payments/customer-balance/funding-instructions.md#create-funding-instructions). The virtual banking details also appear on the hosted invoice page and the PDF.

### Test the default payment method for invoices and subscriptions 

Use specific [test card IDs](https://docs.stripe.com/testing.md?testing-method=payment-methods#cards) to simulate default payment methods being used for subscriptions and invoices.

Attach the payment method to the customer before setting it as the `default_payment_method`. For example, to use `pm_card_visa` as a test Visa payment method:

1. [Attach the test payment method](https://docs.stripe.com/api/payment_methods/attach.md) `pm_card_visa` to the customer associated with the subscription or invoice.
2. Create the subscription or invoice with the attached payment method’s ID as its `default_payment_method`.

The subscription or invoice uses this payment method for payment collection.

## Test customer tax ID verification 

Use these magic tax IDs to trigger certain verification conditions in testing environments. The tax ID type must be the Australian Business Number (ABN), EU VAT Number, or UK Value-Added-Tax (GB VAT) number.

| Number | Type |
| --- | --- |
| `000000000` | Successful verification |
| `111111111` | Unsuccessful verification |
| `222222222` | Verification remains pending indefinitely |

## Automate your tests 

You can set up [automated testing](https://docs.stripe.com/automated-testing.md) for your integration. Use separate sandboxes for local development and continuous integration (CI) so automated tests don’t affect your products, prices, customers, webhook endpoints, settings, or test data.

For testing:

- Be aware of the [data retention policy](https://support.stripe.com/questions/test-mode-subscription-data-retention) for subscription-related data in a sandbox.
- Avoid re-using resources such as [coupons](https://docs.stripe.com/api/coupons.md) and [promotion codes](https://docs.stripe.com/api/promotion_codes.md) across tests.
- Use the [stripe-mock](https://github.com/stripe/stripe-mock) HTTP server, which is based on the Stripe API and closely reflects the API’s behavior.

## See also

- [Sandboxes](https://docs.stripe.com/sandboxes.md)
- [Multiple accounts](https://docs.stripe.com/get-started/account/multiple-accounts.md)