Skip to main content
Polar provides a sandbox environment that allows you to test your integration without affecting production data or processing real payments.

​
Environment Modes

Polar operates in different environment modes:

Production

Live environment with real payments and customer data.API Base URL: https://api.polar.sh

Sandbox

Test environment with simulated payments for safe testing.API Base URL: https://sandbox.polar.sh (same as production during testing)
The sandbox environment uses the same API endpoints as production. The key difference is in the Stripe configuration and organization settings, not the API URL.

​
How Sandbox Mode Works

Sandbox mode is configured at the organization level, not through a separate API endpoint:
  1. Stripe Test Mode: Organizations in sandbox use Stripe’s test mode, which means:
    • No real money is processed
    • You can use Stripe test card numbers
    • Webhooks are triggered with test data
  2. Isolated Data: Each organization’s sandbox data is isolated:
    • Separate customers, subscriptions, and orders
    • Test payments don’t affect production metrics
    • Safe to experiment with any API operations
  3. Same API: Use the same API endpoints and SDKs:
    • Authentication works the same way
    • All API features are available
    • Webhooks function identically

​
Setting Up Sandbox Testing

1

Create a test organization

Create a separate organization in Polar specifically for testing.
2

Configure Stripe test mode

Connect your organization to Stripe using test mode credentials:
  • Use Stripe test API keys
  • Configure test webhook endpoints
  • All payments will use Stripe’s test environment
3

Get API credentials

Generate an Organization Access Token or Personal Access Token for your test organization.
# Your token will work with the same API URL
export POLAR_ACCESS_TOKEN="polar_oat_test_..."
4

Start testing

Make API calls using your test organization credentials.

​
Test Payment Methods

When your organization is connected to Stripe in test mode, you can use Stripe’s test card numbers: 
Card Number: 4242 4242 4242 4242
Expiry: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits

Card Declined: 4000 0000 0000 0002
Insufficient Funds: 4000 0000 0000 9995
Expired Card: 4000 0000 0000 0069

Requires Authentication: 4000 0025 0000 3155
Authentication Failed: 4000 0000 0000 9987

Processing Error: 4000 0000 0000 0119
Disputed Payment: 4000 0000 0000 0259
For a complete list of Stripe test cards, see Stripe’s testing documentation.

​
Testing Subscriptions

Test the complete subscription lifecycle in sandbox mode: 
curl -X POST https://api.polar.sh/v1/subscriptions \
  -H "Authorization: Bearer YOUR_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_test_123",
    "customer_id": "cus_test_456"
  }'

​
Testing Webhooks

Webhooks work the same way in sandbox mode:
1

Set up local webhook endpoint

Use a tool like ngrok or localtunnel to expose your local server:
ngrok http 3000
2

Configure webhook in Polar

Add your webhook endpoint URL in your test organization settings:
https://your-subdomain.ngrok.io/webhooks/polar
3

Test events

Trigger events by performing actions in your sandbox organization:
  • Create a customer
  • Start a subscription
  • Process a test payment
  • Cancel a subscription
4

Verify delivery

Check your webhook endpoint receives events with test data.
For more details on webhook setup and testing, see our Webhooks documentation.

​
Testing Customer State

Verify customer entitlements and subscriptions using the Customer State API: 
curl https://api.polar.sh/v1/customers/cus_test_123/state \
  -H "Authorization: Bearer YOUR_TEST_TOKEN"

​
Testing Usage-Based Billing

Test meters and event ingestion in sandbox mode: 
curl -X POST https://api.polar.sh/v1/events \
  -H "Authorization: Bearer YOUR_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_request",
    "customer_id": "cus_test_123",
    "properties": {
      "endpoint": "/api/data",
      "method": "GET"
    }
  }'

​
Common Test Scenarios

  1. Create a test customer
  2. Create a checkout session
  3. Use a test card to complete payment
  4. Verify subscription activation
  5. Check webhook delivery
  6. Query customer state
  1. Create active subscription
  2. Test usage tracking (if applicable)
  3. Simulate subscription renewal
  4. Test subscription cancellation
  5. Verify cancellation webhooks
  6. Check benefit revocation
  1. Create subscription with failing card
  2. Observe payment failure webhooks
  3. Test payment retry logic
  4. Update payment method
  5. Verify successful retry
  1. Create subscription on lower tier
  2. Upgrade to higher tier mid-cycle
  3. Verify prorated billing
  4. Check updated benefits
  5. Test downgrade scenario

​
SDK Configuration for Testing

Configure your SDKs to use test credentials: 
// Load different tokens based on environment
const polar = new Polar({
  accessToken: process.env.NODE_ENV === 'production'
    ? process.env.POLAR_PROD_TOKEN
    : process.env.POLAR_TEST_TOKEN,
});

​
Debugging Tips

Check Stripe Dashboard

View test payments and events in your Stripe test dashboard to verify payment processing.

Monitor Webhooks

Use the webhook logs in Polar dashboard to see delivery status and payloads.

API Logs

Enable detailed logging in your application to track API requests and responses.

Network Inspector

Use browser dev tools or tools like Postman to inspect API calls.

​
Moving to Production

When ready to go live:
1

Complete Polar account review

Ensure your production organization is approved by Polar’s compliance team.
2

Connect production Stripe account

Switch from Stripe test mode to live mode in your organization settings.
3

Update API credentials

Generate new Organization Access Tokens for your production organization.
4

Update webhook endpoints

Configure webhook URLs to point to your production servers.
5

Deploy with production tokens

Update your application environment variables with production credentials.
6

Monitor initial transactions

Closely monitor your first production transactions to ensure everything works correctly.
Never use production credentials in test environments or commit them to version control. Keep production and test credentials strictly separated.

​
Next Steps

Authentication

Learn about API authentication methods

Customer State

Check customer entitlements and subscriptions

Webhooks

Set up real-time event notifications

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us