Environments & sandbox

How the sandbox and live environments differ, what the sandbox simulates, and its limits.

Subby gives every account two fully separate environments. Build and test in sandbox, then switch your base URL and keys to live when you're ready.

At a glance

	Sandbox	Live
Base URL	`https://sandbox-api.mysubbyapp.com/v1`	`https://api.mysubbyapp.com/v1`
Secret key prefix	`sk_test_` / `rk_test_`	`sk_live_` / `rk_live_`
`livemode` on objects	`false`	`true`
Payments	Simulated by the Subby payment simulator	Processed by our payment partners
Nudges (SMS, WhatsApp, email)	Never delivered; recorded in the nudge outbox	Delivered to real recipients
Webhooks	Delivered to your endpoints, signed the same way	Delivered to your endpoints
Write requests metered	No	Yes
Nudges billed	No	Yes, beyond your allowance
Rate limit	100 requests per minute per key	Depends on your plan, see Rate limits
Test helpers (`/test/*`)	Available	Not available (`404`)
Data retention	Deleted after 90 days without API activity, or when you reset	Kept for the life of your account
Access	Instant on sign-up	After live access approval

Data never crosses over

Plans, customers, subscriptions, webhook endpoints and keys created in sandbox do not exist in live, and the other way round. When you go live you recreate your plans and webhook endpoints in live, usually with the same setup script pointed at the live base URL and key.

IDs look the same in both environments. Check livemode on any object if you need to tell them apart.

What the sandbox simulates

The sandbox runs the same subscription engine as live. Only the edges that touch payment rails and messaging providers are swapped for simulators.

Payments. Instead of real cards, bank accounts and USSD, you use test payment methods that succeed, fail with a specific decline code, or fail a set number of times before succeeding. Use them to test retries end to end.

Nudges. Nothing is sent to real phones or inboxes. Every nudge appears in Dashboard → Developers → Sandbox → Nudge outbox with the rendered message, and through GET /test/nudge-outbox. Test phone numbers let you simulate delivered, failed and unreachable outcomes.

Time. Billing cycles take days or months. Test clocks let you move time forward for a group of customers so you can watch renewals, retries, reminders and escalation happen in minutes.

Events. POST /test/events/trigger sends any webhook event type to your endpoints with realistic data, so you can build handlers before you have real traffic.

Things that behave differently

Checkout pages show a "Sandbox" banner and a test payment method picker instead of real payment forms.
Your Subby invoices are not generated from sandbox activity. GET /usage in sandbox shows your sandbox counts for information only.
Payment processor fields such as processor on charges are always simulator.
Delays are shorter. Simulated payment results arrive in about 2 seconds, so your integration must not assume a payment result is instant in live.

Resetting sandbox data

To start fresh, go to Dashboard → Developers → Sandbox → Reset sandbox, or call:

curl -X POST "https://sandbox-api.mysubbyapp.com/v1/test/reset" \
  -H "Authorization: Bearer $SUBBY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "RESET" }'

Resetting deletes all sandbox plans, customers, subscriptions, charges, nudges, events and test clocks. Your sandbox API keys and webhook endpoints are kept, so your integration keeps working.

Moving to live

When your integration works end to end in sandbox, follow the Going live checklist. In short:

Request live access from the dashboard.
Once approved, create a live secret key.
Recreate plans and webhook endpoints in live.
Point your production configuration at https://api.mysubbyapp.com/v1 with the live key.