Set up a sandbox
Doing this properly takes an afternoon and removes the entire class of integration incidents that begins "we were only testing".
1. Request the tenant
A sandbox is a separate tenant with its own slug. Request it through your usual
support channel, and ask for a slug that is unmistakable in a log at 02:00:
acme-eu-sandbox, never acme-eu-2.
Confirm three things when it arrives:
- Which apps are installed. It should mirror production — a sandbox without the Inventories app cannot test a stock integration.
- That outbound messaging is off or redirected. Nothing from the sandbox should reach a real customer's inbox.
- Its own storefront address, so the integrator can see the effect of what they push.
2. Seed it
An empty sandbox is not testable; a copy of production is not permissible. Build a deliberate seed instead, and keep the file that produced it — that file is your sandbox definition.
| Seed with | Roughly | Include specifically |
|---|---|---|
| Catalog slice | 2,000–5,000 articles | A variant family, a measurement attribute, an article sold in packs of 12, a discontinued one, one with a very long description |
| Price lists | The real structure | A default list, a customer-specific list, a scale price, an expired time-limited price |
| Organizations | 10–20, invented | One with an approval threshold, one blocked, one on punchout, one in a second currency |
| Contacts | 2–3 per organization | One who may only request orders, one who may approve |
| Orders | A handful in each status | pending, placed, in_fulfillment, completed, cancelled |
| Stock | Across a few locations | Zero stock, stock fully reserved, and a negative-availability case |
The practical route for most companies: export the structure from production (attributes, families, categories, price-list layout, channels, markets, tax classes), import it into the sandbox, then load an invented customer and order set on top. Keep both files in version control alongside the project.
3. Issue sandbox keys
The sandbox needs its own API keys — keys are bound to a tenant and cannot reach another one.
Sandbox keys are different in kind from production keys, and it is worth being explicit about how:
| Production key | Sandbox key | |
|---|---|---|
| Scopes | Exactly what the integration needs | Wider is acceptable |
| Who holds it | You, handed over once, into a secret store | The integrator, in their own tooling |
| Name | erp-order-sync-prod | sandbox-integrator-mueller |
| Lifetime | Rotated on a schedule | Revoked when the project phase ends |
| Number of them | As few as possible | One per person or per team is fine |
Two things stay non-negotiable even in a sandbox: the secret is still shown only once, and it still does not go in an email.
4. Write the handover document
One page, given to the integrator with the key. It answers everything they would otherwise ask you three times:
- The tenant slug and the gateway endpoint,
https://api.revenexx.com. - Where the per-tenant API reference lives:
https://api.revenexx.com/v1/openapi.json— this is the authority on what exists, not any prose page. - Which apps are installed.
- The sandbox storefront address.
- Which fixture records to use — the invented organization with an approval threshold, the blocked one, the article sold in packs of 12.
- The refresh and reset cadence, and who to ask.
- Where to go for developer-level questions: the Developer Portal at revenexx.dev.
- Who at your company owns this, and how to reach them.
5. Agree the refresh cadence
Sandbox data drifts from production within weeks. Decide up front:
- Reset — back to the seed. Agree it happens between test rounds, never in the middle of one.
- Refresh — a new seed reflecting current production structure. Once a quarter, and always before a go-live round.
- Freeze — no resets during the final test week before go-live, so results are reproducible.
Put the dates in the project plan. A reset that surprises somebody costs a day of their work and a great deal of goodwill.
What to check
Before you hand it over, run these yourself:
- A call with the sandbox key returns
200, and the same key against the production tenant slug is refused. - The storefront shows the seeded catalog and the invented customers can log in.
- Placing a test order sends no email to any real address.
- A fixture order exists in each status the integrator will need to read.
openapi.jsonon the sandbox lists the resources you expect.
When it does not work
- The integrator sees fewer resources than expected — an app is not installed on the sandbox. Compare with production; see Apps and the Marketplace.
- Sandbox behaves differently from production — usually a settings difference, not a platform one. Approval thresholds, checkout reservation behaviour and channel visibility are the usual three.
- Test emails reached real people — stop, switch messaging off, and treat it as an incident. This is the reason step 1 checks it.
Next
- Test an integration end to end — what to run in it, and the go-live checklist.
- Common API tasks, by job — the recipes the integrator will work through.