Sandbox & Test Mode

Overview

Use test API keys to build and debug your integration without affecting production data. Test keys use the prefix wk_test_ while live keys use wk_live_.

Test Keys

Generate test keys from the dashboard or via the API. Test keys have the same scopes as live keys but operate on sandbox data.

curl -X POST https://whale-gateway.fly.dev/v1/stores/{storeId}/api-keys \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Test Key", "mode": "test", "scopes": ["*"]}'

The response includes your full API key. Store it securely — it cannot be retrieved again.

How It Works

Test keys connect to the same store as your live keys, so you can work with your real product catalog and customer data. The difference is in how side effects are handled:

• •Payment processors run in sandbox mode — no real charges are made.
• •Orders created with test keys are flagged with is_test: true and excluded from analytics.
• •Webhooks fire normally, so you can test your event handlers end-to-end.
• •Email and SMS are suppressed — no messages are sent to real customers.

Payment Testing

Use these test card numbers to simulate different payment outcomes. Any future expiration date and any 3-digit CVC will work.

Switching to Production

When you're ready to go live, replace your wk_test_ key with a wk_live_ key. Same endpoints, same SDK, same code.

// Development
const whale = new WhaleClient({ apiKey: 'wk_test_...' })

// Production
const whale = new WhaleClient({ apiKey: 'wk_live_...' })

Use environment variables to switch between test and live keys without changing code:

const whale = new WhaleClient({
  apiKey: process.env.WHALETOOLS_API_KEY
})

Limitations

Test mode shares the same product catalog and customer data as production. Only payments and orders are sandboxed.

• •Product, customer, and inventory data is shared between test and live modes.
• •Test orders do not decrement inventory or trigger fulfillment workflows.
• •Rate limits apply equally to test and live keys.
• •Test data is automatically purged after 30 days of inactivity.