Sandbox Mode

Test your integration safely without consuming live credits or affecting production data.

Sandbox is not for production

Sandbox keys are licensed for internal evaluation and integration testing only. You may not serve end users, run production traffic, or ship an application on a ph_test_ key — and that includes pilots, betas, trials, and external demos — including while under the 1,000-credit monthly cap. The cap is a resource limit, not a licence.

Production traffic on a sandbox key breaches the Sandbox Terms and is grounds for immediate suspension under Section 3.

How to use the sandbox

Use a sandbox API key (prefix ph_test_); all requests made with a sandbox key automatically run in sandbox mode, regardless of any other parameters. Creating your first sandbox key in the Developer Portal requires accepting the Sandbox Terms.

Authorization: Bearer ph_test_YOUR_SANDBOX_KEY

What's available in sandbox

The sandbox catalog includes a curated subset of real data:

All categories are available (handbags, watches, etc.)
All brands are available
Top models per category:
- Handbags: top 100 most popular models
- Watches: top 20 most popular families
All children of those models: styles, cases, dials, products, variants

This covers the most common real-world items while keeping the sandbox fast and lightweight.

Sandbox behavior

Feature	Sandbox	Live
Permitted use	Evaluation and testing only	Production
Credit consumption	Tracked separately, not billed	Yes
Monthly credit limit	1,000 credits/month	Based on plan
Catalog coverage	Subset	Full catalog
Vision identification	Yes (limited catalog)	Yes (full catalog)
Vision feedback	Validated as live; no rebate, not used for training	Yes
`allow_training`	Validated as live; photos never kept	Yes (if your agreement includes training)
Market estimates	Yes	Yes
Rate limits	Same as live	Based on plan

Vision requests are the same with both keys: with a test key, the response adds a warnings line where the sandbox differs (a reduced catalog, feedback that earns no rebate, photos that are not kept), so your integration sends exactly the requests it will send live.

Sandbox credits reset on the 1st of each month (UTC). When the 1,000-credit limit is reached, test-key requests return a 402 error.

Try it in the API Explorer

The API Explorer in the developer portal runs any v3 endpoint with your sandbox key, no code needed: catalog search with sort, filters and tags, vision identify on your own photo URL, and vision feedback for the prediction you just made.

Going live

Live access is not self-serve. Before you serve any end user:

Submit an access request from Developer Dashboard → API Keys, describing what you're building and where pricing appears in it
We review it against the rules in How pricing may be used
Sign an API Commercial Agreement — this carries the terms your live use runs under, and is negotiated individually (see Usage Policy)
Once approved, generate a live key and swap ph_test_ for ph_live_

# .env.development
PRICE_HERO_API_KEY=ph_test_...

# .env.production
PRICE_HERO_API_KEY=ph_live_...

The API shape is identical, so the swap needs no code changes. The licence is not identical.