Understand the interfaces

The sandbox

A separate tenant your integrator is allowed to break — what belongs in it, what must never be copied into it, and why 'we'll test carefully in production' is not a plan.

A sandbox is a second tenant: its own slug, its own data, its own API keys, its own storefront. It exists so that the answer to "can I try this?" is yes.

What it is

Think of it as a full copy of the platform that happens to contain data nobody will be upset about.

	Production	Sandbox
Tenant slug	`acme-eu`	`acme-eu-sandbox`
Data	Your real catalog, customers and orders	A representative subset, anonymised
API keys	Tightly scoped, few, owned by you	Broad, disposable, handed to the integrator
Who may write	Named integrations only	Anyone working on the project
Consequence of a mistake	A credit note, or a call from a customer	Nothing
Email and messaging	Real, to real people	Off, or redirected to a test inbox
Reset	Never	On request, deliberately

The important line is the last-but-one. A test order placed in production that triggers a real order confirmation to a real buyer is not a test; it is an incident with a support ticket attached.

What it is not

Three misunderstandings, each expensive:

It is not a staging environment for the platform itself. The platform's own releases are not something you stage. What you are testing is your configuration and your integrations.

It is not a performance test rig. Rate limits apply there as they do in production, and the sandbox holds a fraction of your data volume. An import that takes four minutes on 3,000 sandbox products tells you nothing about 400,000 production products. See Rate limits, quotas and fair use.

It is not permanent. Sandbox data drifts from production within weeks — new attributes, new price lists, new customers on one side and not the other. Plan to refresh it rather than to maintain it.

What must never leave production

This is the paragraph to read twice, because getting it wrong is a DSGVO problem rather than an engineering one.

A sandbox is, by design, a place where access controls are loose and the credentials get shared with people outside your company. Real personal data must not be in it.

Copy it	Anonymise it	Never copy it
Product master data, attributes, families	Organization names and addresses	Contact names, email addresses, phone numbers
Category and catalog structure	Customer numbers	Storefront login credentials
Price list structure and scale logic	Order history, if you need volume	Payment data and bank details
Channels, markets, tax classes		Credit limits and blocked status
Approval rules and role definitions		Anything a person could be identified by

The workable version for most companies: copy the structure, invent the people. Take the real catalog, the real price-list layout and the real approval rules, and populate them with a dozen invented organizations — Testkunde Nord GmbH with contacts at @example.com — that behave like your real customers without being any of them.

"We anonymised it" is a claim somebody has to be able to defend. Replacing names but keeping customer numbers, order histories and delivery addresses is not anonymisation — the combination re-identifies the customer trivially. If you cannot argue that a record no longer relates to an identifiable person, do not put it in a tenant whose keys are held by a third party.

Seeded data: what a useful sandbox contains

An empty sandbox is not testable. A full copy of production is not permissible. The useful middle is a deliberate seed:

A slice of the catalog, a few thousand articles, chosen to include the awkward cases: a variant family, an article with a measurement attribute, one with a long description, one sold in a packaging unit of 12, one that is discontinued.
The real price-list structure — a default list, a customer list, a scale price, a time-limited price — with invented amounts.
Ten to twenty invented organizations, covering the range that matters: one with an approval threshold, one blocked, one on a punchout channel, one paying on account, one in a second currency.
A handful of orders in each status, so an integrator can test reading pending, placed, in_fulfillment, completed and cancelled without waiting for one to occur.
Stock levels that include zero and negative-availability cases, because those are the ones that break integrations.

That seed is worth building once, carefully, and keeping as the definition of a sandbox refresh.

Resetting

A reset wipes the sandbox back to its seed. It is deliberate, and it is what makes the sandbox genuinely safe to break: the recovery from a catastrophic test is not a repair, it is a reset.

Two habits make resets painless:

Never keep anything in the sandbox that only exists there. Configuration worth keeping gets written down or exported. A reset should destroy nothing anyone minds.
Agree the reset cadence with your integrator up front — typically before each major test round. A reset in the middle of somebody's test week is worse than no reset at all.

Promoting configuration to production

The point of testing in the sandbox is that the thing you tested is the thing that goes live. That does not happen by itself.

What promotes cleanly, and how:

Configuration	How it moves
Attributes, families, categories	Export and import, or re-create from the written spec
Price list structure	Re-create; the amounts are different anyway
Import and export profiles, field mappings	Re-create with the same codes — see Field mapping
Webhook subscriptions	Re-create, pointing at the production receiver, with a new secret
API keys	Never. New tenant, new keys, new scopes
Workflows and schedules	Re-create, then check every schedule time

Note what is not on that list: there is no button that copies a sandbox on top of production. Treat promotion as a documented, repeatable procedure, and write it down as you do it the first time — that document is your disaster-recovery runbook as well.

The codes are the contract. If an attribute is thread_size in the sandbox and thread_size_1 in production, every mapping, every export profile and every integration breaks at go-live. Use the same codes in both, always. This is the single most common go-live failure and it costs a day every time.

When you do not have a sandbox tenant

Two smaller safety nets exist inside a single tenant and are worth knowing, because they cover a lot of everyday risk:

Staging on an import. Import & Export can load a file into a preview area instead of your live data, so you can look at what would have happened before it happens. Use it the first time you run any new file — see Bulk exports.
A test channel. A channel nobody's customers can reach lets you check storefront-visible configuration without a second tenant.

Neither replaces a sandbox for integration work, because neither gives an outside integrator a place where a mistake is free.

Set up a sandbox — provision, seed, hand over.
Test an integration end to end — what to actually run in it before go-live.

Edit this page

Keys, scopes and tenants

Three kinds of identity, one credential per integration, and the scope discipline that means a compromised key costs you an afternoon rather than your catalog.

Rate limits, quotas and fair use

The limit is per tenant, not per key — which means your BI job can throttle your storefront. What 429 means, how to back off, and when a loop should have been a bulk job.