Sandbox

The SandboxService class (accessed via client.sandbox) is developer tooling for the sandbox (test) environment: reset test data in one call, fast-forward time so time-dependent behavior fires immediately, replay a webhook without recreating the underlying record, and create the discount instruments a checkout needs. Each removes a manual setup step from a test run, so the run can start from a known state. Promotions, gift cards, and campaigns are normally created by the merchant in their admin, which always writes production data. The seed methods are how those instruments come to exist in your sandbox, so a sandbox order can carry a discount. A sandbox order never lowers the merchant’s live stock. Sandbox stock levels give a variant a sandbox-only count instead, which test keys read and sandbox orders take from, so low-stock and sold-out behaviour can be exercised.

Every Sandbox method requires a secret test key (tybrite_sk_test_*). Publishable keys and live keys are rejected with 403. These operations only ever touch your sandbox data — your live data and store configuration are never affected.

Methods

`resetSandbox`

Wipe all of your store’s sandbox test data immediately — orders, customers, carts, wishlists, returns, store credits, reviews, messages, analytics events, webhook events, and more — instead of waiting for the automatic 30-day cleanup. Returns 204 No Content.

await client.sandbox.resetSandbox();
// returns 204 No Content (your sandbox is now empty)

deleteSandboxData (mapped to DELETE /v1/sandbox/data) is an exact alias if you prefer a DELETE:

await client.sandbox.deleteSandboxData();

`advanceSandboxTime`

Fast-forward your sandbox by a number of days so time-dependent behavior happens now. It back-dates your sandbox abandoned carts, stock reservations, and analytics events, then runs the expiry/rollup jobs — so abandoned-cart windows elapse, reserved stock is released, and analytics roll forward, without waiting. The response reports what was shifted and what was intentionally left alone.

const result = await client.sandbox.advanceSandboxTime({
  requestBody: { advance_days: 30 }
});
// returns {
//     advanced_days: 30,
//     shifted: { shopping_carts: 3, stock_reservations: 1, storefront_events: 120 },
//     not_shifted: { promotions: "...", gift_cards: "...", trial: "...", subscription_renewal: "..." }
//   }

Subscription trials/renewals are real account state and are not time-shifted; promotions and gift cards aren’t shifted either. To test their expiry, seed one with a near-future end_date or expiry_date using the methods below. The not_shifted object explains each.

`replaySandboxWebhook`

Re-send a previously-recorded sandbox webhook event to all your matching, enabled webhook endpoints — so you can re-test your handler without recreating the order/customer/etc. Identify the event by event_id, or by type to replay the most recent sandbox event of that type. The original event is unchanged.

const res = await client.sandbox.replaySandboxWebhook({
  requestBody: { type: 'order.created' }
});
// returns { replayed_event_id: '…', results: [ { endpoint_id, success, status_code }, … ] }

await client.sandbox.replaySandboxWebhook({
  requestBody: { event_id: 'evt_…' }
});

`seedSandboxPromotion`

Create a promotion in your sandbox so a sandbox order can carry a cart discount. Every field is optional — the defaults produce an active percentage promotion starting today and running for 30 days. The environment is set by Galactic Core and is never read from your request body.

const { promotion } = await client.sandbox.seedSandboxPromotion({
  requestBody: { name: 'Launch week', type: 'percentage', value: 15, min_purchase: 50 }
});

Response

{
  "promotion": {
    "id": "583bcfa6-a86a-4bc4-87e0-1a70e6294bda",
    "name": "Launch week",
    "type": "percentage",
    "value": "15",
    "min_purchase": 50,
    "start_date": "2026-09-07",
    "end_date": "2026-10-07",
    "status": "active",
    "environment": "sandbox"
  }
}

type accepts percentage, fixed, bogo, or bundle. percentage and fixed discount the whole cart; bogo and bundle carry product lists configured by the merchant.

`seedSandboxGiftCard`

Create a gift card in your sandbox, so redemption can be exercised end to end. The defaults issue an active 50.00 digital card expiring in a year with a generated SBX-… code. The same code is valid for your test key and unknown to a live key.

const { gift_card } = await client.sandbox.seedSandboxGiftCard({
  requestBody: { code: 'SBX-DEMO-100', value: 100 }
});

Response

{
  "gift_card": {
    "id": "026da417-6ae7-4152-a029-696309e74b05",
    "code": "SBX-DEMO-100",
    "value": 100,
    "balance": 100,
    "status": "active",
    "type": "digital",
    "expiry_date": "2027-09-07",
    "environment": "sandbox"
  }
}

`seedSandboxCampaign`

Create a marketing campaign in your sandbox. A campaign is a budget with a discount attached: it discounts an order like a promotion, but stops once its budget is spent — so this is how budget exhaustion is exercised without spending a real one. applies_to scopes where it applies: online for storefront orders, pos for in-store, or all for both. A campaign scoped to one channel does not discount the other.

const { campaign } = await client.sandbox.seedSandboxCampaign({
  requestBody: { name: 'Autumn push', budget: 500, discount_value: 20, applies_to: 'online' }
});

Response

{
  "campaign": {
    "id": "d5814e95-e68b-4a98-95bf-cb945f413052",
    "name": "Autumn push",
    "type": "seasonal",
    "budget": 500,
    "budget_spent": 0,
    "budget_remaining": 500,
    "discount_type": "percentage",
    "discount_value": 20,
    "applies_to": "online",
    "start_date": "2026-09-07",
    "end_date": "2026-10-07",
    "status": "active",
    "environment": "sandbox"
  }
}

As sandbox orders apply the campaign, budget_spent rises and budget_remaining falls. Once the budget is exhausted the campaign stops discounting, which is the behavior a live campaign has when its budget runs out.

`seedSandboxB2BBuyerAccount`

Create a B2B buyer account in your sandbox. This is what makes the /v1/b2b/* endpoints reachable with a test key: every B2B endpoint resolves a buyer account for the calling customer before doing anything else, and returns 403 when there isn’t one. Pass the customer_id of a customer you created with a test key. A production customer is refused, so a sandbox buyer account can never attach to one of the merchant’s real customers.

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

Response

{
  "buyer_account": {
    "id": "e23b79a8-1c9c-4594-b587-50bb0518e55a",
    "customer_id": "92a2fe11-2a7f-46e4-acf0-541b5e77828a",
    "payment_terms": "net30",
    "credit_limit": 5000,
    "credit_used": 0,
    "tax_exempt": false,
    "on_hold": false,
    "checkout_policy": null,
    "environment": "sandbox"
  }
}

The store still has to have B2B enabled. If it does not, every B2B endpoint keeps returning 404, and seeding a buyer account does not change that.

`seedSandboxPricingRule`

Create a dynamic-pricing rule in your sandbox, so /v1/prices/* returns a rule-adjusted price you can build against. Rules are environment-scoped: a test key resolves only the rules you seed, and a live key only the merchant’s real ones. Seeding also refreshes your sandbox pricing cache, so the rule takes effect on your next request rather than when the cache expires.

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

Response

{
  "pricing_rule": {
    "id": "61156d88-c51f-48ec-a44b-61d10d8b2992",
    "name": "Sandbox half price",
    "rule_type": "percentage",
    "discount_value": 50,
    "applies_to": "all",
    "target_ids": [],
    "priority": 0,
    "start_date": "2026-09-07T00:00:00+00:00",
    "end_date": "2026-10-07T00:00:00+00:00",
    "is_active": true,
    "environment": "sandbox"
  }
}

rule_type accepts percentage, fixed_amount, fixed_price and markup. To scope a rule, set applies_to to category, product or collection and pass the matching ids in target_ids — a scoped rule with no targets matches nothing and is refused.

`setSandboxStockLevels`

Set a sandbox-only stock level for one or more variants. For a variant with a level, a test key reads the level in place of live stock everywhere stock appears — product reads, priced products, shoppable posts and lookbooks, cart and wishlist stock checks, and checkout reservations — and a paid sandbox order takes its quantity from the level. A level of 0 makes the variant sold out for test keys, so adding it to a cart or reserving it is refused. Setting a level again replaces it. Send one level as { variant_id, stock }, or up to 100 as items. Every variant must belong to your store. Live keys, and the merchant’s own admin, keep reading live stock.

const { stock_levels } = await client.sandbox.setSandboxStockLevels({
  requestBody: { items: [{ variant_id: '86eb90c5-48ea-41b0-a82e-069b1b170f1e', stock: 0 }] }
});

Response

{
  "stock_levels": [
    {
      "variant_id": "86eb90c5-48ea-41b0-a82e-069b1b170f1e",
      "product_id": "f7e24571-1fa9-4264-9ca4-298de2336a35",
      "name": "The Multi-managed Snowboard",
      "variant_name": "Default",
      "sku": "sku-managed-1",
      "stock": 0,
      "live_stock": 80,
      "updated_at": "2026-10-03T23:14:17.072238+00:00"
    }
  ]
}

A paid sandbox order for more than the level still records, takes the level to 0, and reports the shortfall in post_processing_warnings with the stock_reduction stage, as a live order does.

`listSandboxStockLevels`

List the sandbox stock levels set for your store, most recently changed first, each beside the variant’s live stock.

const { stock_levels } = await client.sandbox.listSandboxStockLevels();

Response

{
  "stock_levels": [
    {
      "variant_id": "86eb90c5-48ea-41b0-a82e-069b1b170f1e",
      "product_id": "f7e24571-1fa9-4264-9ca4-298de2336a35",
      "name": "The Multi-managed Snowboard",
      "variant_name": "Default",
      "sku": "sku-managed-1",
      "stock": 0,
      "live_stock": 80,
      "updated_at": "2026-10-03T23:14:17.072238+00:00"
    }
  ]
}

`deleteSandboxStockLevel`

Remove the sandbox stock level for one variant, which then reads live stock again with a test key. Returns 404 when no level is set for that variant.

await client.sandbox.deleteSandboxStockLevel({ variantId: '86eb90c5-48ea-41b0-a82e-069b1b170f1e' });

Response

{
  "success": true,
  "message": "Sandbox stock level removed; the variant reads live stock again",
  "removed": 1
}

`clearSandboxStockLevels`

Remove every sandbox stock level for your store. resetSandbox also removes them.

const { removed } = await client.sandbox.clearSandboxStockLevels();

Response

{
  "success": true,
  "message": "2 sandbox stock levels removed",
  "removed": 2
}

Response Codes

Code	Meaning
`204`	Reset succeeded (no body).
`201`	A sandbox promotion, gift card, campaign, B2B buyer account, or pricing rule was created.
`200`	Time-travel / replay succeeded (summary returned), or sandbox stock levels were set, listed or removed.
`400`	Invalid request — `advance_days` out of 1–3650, neither `event_id` nor `type`, an unknown promotion `type` or campaign `discount_type`, a non-positive value, a `start_date` in the past, or a stock level that is not a whole number from 0 to 1,000,000.
`401`	Missing or invalid API key.
`403`	Not a secret test key — Sandbox tools require `tybrite_sk_test_*`.
`404`	No matching sandbox webhook event to replay, no sandbox customer with that id, a variant that does not belong to your store, or no stock level set for that variant.
`409`	That sandbox customer already has a B2B buyer account.
`429`	Rate limit exceeded.
`500`	Internal server error.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Methods

`resetSandbox`

`advanceSandboxTime`

`replaySandboxWebhook`

`seedSandboxPromotion`

`seedSandboxGiftCard`

`seedSandboxCampaign`

`seedSandboxB2BBuyerAccount`

`seedSandboxPricingRule`

`setSandboxStockLevels`

`listSandboxStockLevels`

`deleteSandboxStockLevel`

`clearSandboxStockLevels`

Response Codes

​Methods

​resetSandbox

​advanceSandboxTime

​replaySandboxWebhook

​seedSandboxPromotion

​seedSandboxGiftCard

​seedSandboxCampaign

​seedSandboxB2BBuyerAccount

​seedSandboxPricingRule

​setSandboxStockLevels

​listSandboxStockLevels

​deleteSandboxStockLevel

​clearSandboxStockLevels

​Response Codes

Methods

`resetSandbox`

`advanceSandboxTime`

`replaySandboxWebhook`

`seedSandboxPromotion`

`seedSandboxGiftCard`

`seedSandboxCampaign`

`seedSandboxB2BBuyerAccount`

`seedSandboxPricingRule`

`setSandboxStockLevels`

`listSandboxStockLevels`

`deleteSandboxStockLevel`

`clearSandboxStockLevels`

Response Codes