Sandbox & Test Environment

Galactic Core ships with a built-in sandbox: a fully isolated test environment that lives inside the same API. There is no separate base URL and no separate account — you switch environments purely by which API key you authenticate with. This makes the sandbox ideal for local development, CI pipelines, and AI agents that need to safely exercise write endpoints (create orders, register customers, add to carts) without ever touching a merchant’s real data.

Test keys vs. live keys

The key prefix is the only thing that selects an environment. Every store has both pairs.

Prefix	Environment	What it touches
`tybrite_pk_live_…` / `tybrite_sk_live_…`	Production	The merchant’s real customers, orders, and inventory
`tybrite_pk_test_…` / `tybrite_sk_test_…`	Sandbox	Isolated test data, never mixed with production

The two never cross. A test key only ever reads and writes sandbox data; a live key only ever touches production. There is no flag to flip and no header to set — the environment follows the key automatically.

Every authenticated response carries a Tybrite-Environment: production | sandbox header, so you can always confirm which environment resolved for a request.

What is isolated

Transactional data you create through the API is stamped with the environment of the key that created it. That includes:

Orders
Customers
Carts and wishlists
Product reviews
Messaging conversations
Returns

A sandbox record is invisible to a live key, and vice versa — to the other environment, the record simply does not exist (a cross-environment lookup returns 404, never a hint that the record lives elsewhere). Discount instruments are isolated too. Promotions, gift cards, and campaigns each belong to one environment: a test key resolves only sandbox instruments, and a live key only real ones. Because these are normally created by the merchant in their admin — which always writes production — you create your own with the seed endpoints rather than borrowing the merchant’s. Catalog data is shared. Products, categories, and collections are read-as-is in both environments — a test key reads the merchant’s real catalog, so you can build and test a realistic storefront against actual products. It just gets no production transactional data tied to those reads: a test key sees only the orders, customers, and carts created in sandbox. A test key never changes the merchant’s stock. A sandbox order goes through the full order lifecycle — it is created, marked paid, and settles any stock it reserved at checkout — and reports success as a live order does, but it never lowers the merchant’s real stock count. Reservations made with a test key count only against other sandbox reservations, so sandbox checkouts never hold back stock from real customers. By default a test key reads the merchant’s live stock; a sandbox stock level gives a variant a sandbox-only count instead.

When you initialize a payment with a test key, the underlying payment provider is forced into test mode automatically — regardless of the store’s live payment settings. A sandbox checkout can never create a real charge.

A test key sees every provider and integration the merchant has configured, including ones still on test credentials. A sandbox checkout can therefore list providers labelled test or sandbox, which is what makes an integration testable before it is live. Live keys resolve the same configuration differently: a provider or integration holding test credentials is not offered to a real customer and is refused if requested directly — see Guardrails. The provider list a sandbox key returns is consequently a superset of the one a live key returns for the same store.

Sandbox data is invisible in the merchant’s app

Sandbox rows exist only for API testing. They never appear in the merchant’s admin dashboard, the storefront, reports, or anywhere in the product — so your test traffic can’t pollute a merchant’s numbers or clutter their order list.

Automatic cleanup

Sandbox data is automatically purged after 30 days, so a sandbox record is not a durable store — a test suite that needs particular data re-seeds it rather than assuming a previous run’s rows are still there. The purge can also be triggered on demand rather than waited for.

API keys are never auto-deleted. Only the transactional sandbox data (orders, customers, carts, reviews, messaging, etc.) is cleaned up. Your test keys remain valid until you remove them yourself.

Developer tools

These operations control sandbox state directly. All require a secret test key (tybrite_sk_test_*), only ever affect your sandbox data, and are available via client.sandbox in the SDK (full reference: SandboxService).

Sandbox reset

Removes all sandbox test data in one call, ahead of the 30-day cleanup — a clean slate before a test run.

await client.sandbox.resetSandbox();           // → 204 No Content
// or the DELETE alias: await client.sandbox.deleteSandboxData();

Time travel

Advances your sandbox by N days, so time-dependent behaviour resolves without a real wait: Galactic Core back-dates your sandbox data, elapsing abandoned-cart windows, releasing reserved stock, and rolling analytics forward.

const result = await client.sandbox.advanceSandboxTime({ requestBody: { advance_days: 30 } });
// → { advanced_days: 30, shifted: { shopping_carts, stock_reservations, storefront_events }, not_shifted: {…} }

The response’s not_shifted explains what is intentionally left alone. To test promotion or gift-card expiry, seed one with a near-future end date using the endpoints below.

Sandbox stock levels

POST /v1/sandbox/stock gives a variant a sandbox-only stock count, so low-stock and sold-out behaviour can be tested without touching the merchant’s inventory. A test key reads the level in place of live stock wherever stock appears — product and priced-product reads, shoppable posts and lookbooks, cart and wishlist stock checks, and checkout reservations — and paid sandbox orders take from it. A level of 0 makes the variant sold out for test keys.

await client.sandbox.setSandboxStockLevels({
  requestBody: { variant_id: '86eb90c5-48ea-41b0-a82e-069b1b170f1e', stock: 1 },
});
// The first sandbox checkout for this variant succeeds; the next is refused as out of stock.

GET /v1/sandbox/stock lists the levels beside each variant’s live count, DELETE /v1/sandbox/stock/{variant_id} returns one variant to live stock, and DELETE /v1/sandbox/stock or a sandbox reset removes them all. Live keys and the merchant’s admin always read live stock.

Webhook replay

Re-sends a recorded sandbox webhook event to your sandbox endpoints (those created with a test key) without recreating the underlying order or customer, so a handler can be iterated on against the same payload.

// Replay the most recent sandbox event of a type, or pass { event_id } for a specific one.
await client.sandbox.replaySandboxWebhook({ requestBody: { type: 'order.created' } });

Seed discount instruments

A sandbox order with nothing to discount only exercises half a checkout. Promotions, gift cards, and campaigns are created by the merchant in their admin, which always writes production data — so these three endpoints are how each comes to exist in your sandbox. Every field is optional. The defaults produce a ready-to-use instrument, so an empty body is enough to get a working discount.

// A 15% cart promotion, active today, running 30 days.
const { promotion } = await client.sandbox.seedSandboxPromotion({
  requestBody: { value: 15 }
});

// A gift card with a known code, so a test can redeem a specific one.
const { gift_card } = await client.sandbox.seedSandboxGiftCard({
  requestBody: { code: 'SBX-DEMO-100', value: 100 }
});

// A campaign: a budget with a discount attached, scoped to online orders.
const { campaign } = await client.sandbox.seedSandboxCampaign({
  requestBody: { budget: 500, discount_value: 20, applies_to: 'online' }
});

A campaign stops discounting once its budget is spent, so seeding one with a small budget is how you exercise budget exhaustion without spending a real one.

Seed a dynamic-pricing rule

Dynamic pricing is the other thing that changes what a shopper is charged, and it is environment- scoped for the same reason: a test key resolves only the rules you seed, never the merchant’s real pricing strategy.

const { pricing_rule } = await client.sandbox.seedSandboxPricingRule({
  requestBody: { rule_type: 'percentage', discount_value: 50 }
});

/v1/prices/* then returns the rule-adjusted price for your test key, and the unchanged price for a live one. Seeding refreshes your sandbox pricing cache, so the rule applies on the next request.

Reach the B2B endpoints

The /v1/b2b/* endpoints resolve a B2B buyer account for the calling customer before doing anything else, and refuse the request when there isn’t one. Buyer accounts are created by the merchant in their admin, so a test key has none — which makes the whole B2B surface unreachable until you seed one.

const { buyer_account } = await client.sandbox.seedSandboxB2BBuyerAccount({
  requestBody: { customer_id: customer.id, payment_terms: 'net30', credit_limit: 5000 }
});

Pass a customer you created with a test key; a production customer is refused. The store must also have B2B enabled — if it does not, the B2B endpoints keep returning 404 whether or not a buyer account exists.

Seeded instruments are sandbox rows like any other: they never appear in the merchant’s admin, they are cleared by a reset, and they are removed by the automatic 30-day cleanup. A test run that needs a particular instrument seeds it rather than assuming a previous run’s is still there.

How to use it

There is nothing to set up. Authenticate with a test key and you are in the sandbox. See the Authentication guide for the full key reference.

import { Tybrite } from '@tybrite-labs/sdk';

// A test secret key → every call runs against the sandbox.
const client = new Tybrite({
  apiKey: process.env.TYBRITE_SANDBOX_SECRET_KEY // tybrite_sk_test_...
});

// Safely create a test order — it lands in sandbox, never in the merchant's real data.
const order = await client.orders.createOrder({
  idempotencyKey: crypto.randomUUID(),
  requestBody: {
    customer_email: 'test-shopper@example.com',
    items: [{ variant_id: 'var_123', quantity: 1 }]
  }
});

# The tybrite_sk_test_ prefix is all it takes — no extra header, no separate URL.
curl -X POST "https://api.tybritelabs.com/v1/orders" \
     -H "Authorization: Bearer tybrite_sk_test_YOUR_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "customer_email": "test-shopper@example.com",
           "items": [{ "variant_id": "var_123", "quantity": 1 }] }'
# Response includes: Tybrite-Environment: sandbox

Build and test your entire integration with tybrite_sk_test_* keys, including in CI. When you’re ready to go live, swap to a tybrite_sk_live_* key — the right environment follows automatically, with no code changes.

Introduction

How GC Works

Build with AI

Extend the platform

Commerce capabilities

Distribute

Native Integrations

Resources

Test keys vs. live keys

What is isolated

Sandbox data is invisible in the merchant’s app

Automatic cleanup

Developer tools

Sandbox reset

Time travel

Sandbox stock levels

Webhook replay

Seed discount instruments

Seed a dynamic-pricing rule

Reach the B2B endpoints

How to use it

​Test keys vs. live keys

​What is isolated

​Sandbox data is invisible in the merchant’s app

​Automatic cleanup

​Developer tools

​Sandbox reset

​Time travel

​Sandbox stock levels

​Webhook replay

​Seed discount instruments

​Seed a dynamic-pricing rule

​Reach the B2B endpoints

​How to use it

Test keys vs. live keys

What is isolated

Sandbox data is invisible in the merchant’s app

Automatic cleanup

Developer tools

Sandbox reset

Time travel

Sandbox stock levels

Webhook replay

Seed discount instruments

Seed a dynamic-pricing rule

Reach the B2B endpoints

How to use it