Test Mode

Test mode provides a completely isolated data environment for development and testing. Every resource you create in test mode — products, orders, customers, inventory levels — lives in a separate namespace from your live data. Nothing you do in test mode affects your production store.

How It Works

Test mode is determined entirely by your API key prefix. There is no separate flag, toggle, or configuration:

Key prefix	Mode	Usage
sk_test_	Test	Secret key for test mode
pk_test_	Test	Publishable key for test mode
sk_live_	Live	Secret key for production
pk_live_	Live	Publishable key for production

When you authenticate a request with a test key, Hydra routes it to your test data. When you use a live key, it routes to production data. No additional headers or parameters are needed.

Admin JWT Requests

For JWT-authenticated admin requests (e.g. from the admin panel), there are no API key prefixes to signal the mode. Instead, pass the X-Test-Mode: true header to switch to test data:

curl https://api.hydrajs.dev/v1/products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Test-Mode: true"

Data Isolation

Test and live environments are fully isolated. Each maintains its own:

• Products and variants — create test products without polluting your catalog
• Orders — place test orders without generating real fulfillments
• Customers — register test customers without mixing into your customer base
• Inventory — adjust stock levels independently
• Collections — organize test products into test collections
• Webhooks — fire against test-mode endpoints
• Discounts and promotions — validate discount logic before going live

No real payments are processed in test mode. Checkout flows complete without charging any payment method, so you can test the full purchase funnel safely.

Webhooks in Test Mode

Webhooks fire in test mode just as they do in live mode. Events created by test-mode actions are delivered to your registered webhook endpoints with is_test: true in the payload. This lets you verify your webhook handlers end-to-end without affecting live integrations.

SDK Usage

Initialize the SDK with a test key to work in test mode, or a live key for production:

import Hydra from '@gethydra/sdk';

// Test mode
const testClient = new Hydra({
  api_key: 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

// Live mode
const liveClient = new Hydra({
  api_key: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

The client behaves identically in both modes — the only difference is which data environment your requests are routed to.

Switching Between Modes

You can maintain two client instances if your application needs to access both environments:

import Hydra from '@gethydra/sdk';

const test = new Hydra({
  api_key: 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

const live = new Hydra({
  api_key: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

// Create a product in test mode
const testProduct = await test.products.create({
  title: 'Test Widget',
  status: 'active',
});

// List live products (completely separate data)
const liveProducts = await live.products.list();

Best Practices

• Always develop against test mode. Use test keys in your local environment and staging deployments. Only switch to live keys in production.
• Use test keys in CI/CD. Automated tests and integration pipelines should always use sk_test_ keys to avoid creating real data.
• Seed test data via the API. Use scripts with your test secret key to populate products, customers, and inventory for consistent testing environments.
• Test webhooks end-to-end. Register a webhook endpoint and verify it receives events correctly in test mode before enabling it for live traffic.
• Keep test data clean. Periodically clear out stale test data to keep your test environment manageable. Soft-deleted resources are automatically purged after 30 days.