Sandbox

A sandbox is a test environment for a subscription or billing platform where a business can build and try out its setup, such as plans, pricing, and gateway configuration, without processing real payments or affecting live customer data.

A sandbox is typically the default environment a business starts in when it first sets up a subscription platform, before it has any real, paying customers. Transactions run in a sandbox are routed through a test payment gateway that uses predefined test card and bank account numbers rather than real ones, so nothing of value actually changes hands. A sandbox is meant to be full featured: a business can configure plans, promotions, payment gateways, and dunning policies there, and that configuration is generally intended to carry over when the business moves to a live, production environment. Sandboxes are a general software-testing concept rather than something specific to subscription and billing platforms, but the same idea applies directly to them.

Why a sandbox matters

Testing in a sandbox before going live reduces the risk of misconfigured pricing, broken payment flows, or incorrect dunning behavior reaching real customers. Because a sandbox uses test transactions rather than real money, a team can experiment freely, break things, and fix them, without financial consequences or exposing customers to a broken checkout experience. Moving from a sandbox to a live production environment is typically a significant, often irreversible step, so understanding what a sandbox does and does not carry over is important before flipping that switch.

How to use a sandbox

1. Build out the core configuration in the sandbox first, including plans, pricing, payment gateway connections, and dunning or renewal policies.

2. Use the test payment credentials provided in the sandbox, rather than real card numbers, to simulate transactions.

3. Test as many real world scenarios as practical, keeping in mind that a test gateway may not perfectly replicate every outcome a live gateway would produce.

4. Clear out test data before going live if the platform offers a way to do so, since old test accounts and transactions generally should not carry into production.

5. Confirm the setup is fully tested before switching to production, since that switch is often permanent and cannot be undone.

Benefits and examples

A sandbox lets a team validate a full setup end to end, from a customer signing up to a payment being collected to a dunning email going out, before any of it touches a real customer or a real payment. For example, a business preparing to launch a new pricing plan can build it in the sandbox, run test transactions with sample cards, and confirm invoices, taxes, and renewal behavior all work as expected, before making that plan available to actual subscribers.

A sandbox is also useful for testing a specific gateway integration, since some gateways treat their sandbox and production endpoints as entirely separate, requiring their own configuration in each environment.

Sandboxes in Recurly

Recurly gives every new site a sandbox by default, so a business can fully trial the service without using real credit cards, with all sandbox transactions routed through the Recurly Test Gateway using predefined test card and bank account numbers. Recurly's sandbox is designed to be full featured, letting a business configure plans, promotions, payment gateways, and dunning policies there and carry that setup forward into production. Recurly also provides a Clear Test Data option to remove test accounts, subscriptions, and transactions from a sandbox site before going live, though it does not affect core configuration like plans, coupons, or email templates, and it does remove connected third-party integrations and webhook endpoints, so those need to be reconnected afterward. Recurly treats the move to a production site as a one-way switch: a site cannot be reverted from production back to sandbox or development mode, and test credit cards will not work once a site is live. Test gateway and Production cover the related environments in more detail.

Frequently asked questions

What is the difference between sandbox mode and production mode? Sandbox mode is a test environment where transactions are simulated using test payment credentials and do not involve real money, while production mode processes real, live customer payments. Sandbox is generally the default starting environment, and switching a site to production mode is typically irreversible.

Can I use real credit cards in a sandbox? No. A sandbox is built around test payment credentials, and using a live card in that environment would not represent an accurate test of how a real transaction behaves. On Recurly specifically, test credit cards only work on a sandbox site and will not work on a production site.

Will everything I configure in a sandbox carry over to production? Core configuration, such as plans, pricing, and policies, is generally designed to carry over from a sandbox to production. Test data itself, such as test customer accounts and test transactions, typically does not and usually needs to be cleared out separately before going live.

Can I switch a sandbox site back to production, or a production site back to sandbox? A site can generally be moved from a sandbox environment into production, but on Recurly this move cannot be reversed. Once a site has been switched to production, it cannot be changed back to sandbox or development mode.

Do sandbox sites expire? On Recurly, sandbox sites do not expire simply from the passage of time. A sandbox site receives a warning at 60 days of inactivity, and Recurly closes the site at day 70 if the inactivity persists.