> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/reference/generic/sandbox.md).

# Sandbox

tiun gives you **two fully independent environments** that run **in parallel**: **live** and **sandbox**.

Think of sandbox as a separate copy of your tiun setup — same SDK and checkout behavior, but its own catalog, snippet ID, domains, API keys, customers, and analytics. Nothing syncs or carries over automatically between the two.

**Live** is the default: real customers, real payments, your production domain. `localhost` is blocked in live.

**Sandbox** is for building and testing: simulated payments, test customers, and your development flow. `localhost` is enabled by default on any port in sandbox when you use sandbox settings (`sandbox: true` plus a sandbox snippet ID).

***

## What is independent in each environment

Everything you configure in tiun exists **twice** — once per environment. A sandbox product ID never works in live, and a live API key never works against the sandbox API.

| Resource                      | Live                                                          | Sandbox                                                                                |
| ----------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Authorized domains            | Production domains only (e.g. `yoursite.com`), no `localhost` | Dev / staging domains (e.g. `staging.yoursite.com`); `localhost` is enabled by default |
| Snippet ID                    | Live snippet                                                  | Sandbox snippet                                                                        |
| Products & pricing            | Your live catalog                                             | Separate test catalog                                                                  |
| Product IDs                   | `p-live-...`                                                  | `p-test-...`                                                                           |
| API keys                      | Live keys only                                                | Sandbox keys only (not shared)                                                         |
| Customers, sessions, payments | Real                                                          | Test / simulated                                                                       |
| Dashboard data                | Live analytics                                                | Sandbox analytics                                                                      |

Checkout, events, paywalls, and access control work the same way in both environments. Only the data, domains, credentials, and payment processing differ.

***

## Selecting an environment in your app

In the browser SDK, pass `sandbox: true` to target sandbox. Omit `sandbox` or set `sandbox: false` to target live (the default).

```javascript
tiun.init({
  snippetId: 'YOUR_SNIPPET_ID', // must match the environment you're targeting
  language: 'en',
  sandbox: true, // remove this line to target your live environment
});
```

Use the **snippet ID** from the environment you're building against. Sandbox and live each have their own snippet ID in the dashboard.

***

## Dashboard: two parallel setups

In the [my.tiun.business dashboard](https://my.tiun.business/), the **Sandbox** toggle in the sidebar switches which environment you're viewing and editing — products, customers, snippet ID, and API keys all belong to that view.

You set up **live** and **sandbox** separately:

* **Live** — register your production domain and create your real product catalog.
* **Sandbox** — the first time you open the sandbox view, register your test domain (prefer test/staging; use your live domain if needed as a fallback), then create test products with the same structure you plan to use in live.

Both environments can be fully configured at the same time and run in parallel.

For a step-by-step walkthrough, see [setting up your environment](/guides/getting-started/set-up-environment.md).

{% hint style="info" %}
**Your app and the dashboard should target the same environment while you're working.** If the dashboard is on live but your SDK has `sandbox: true` (or the other way around), snippet IDs, product IDs, and sessions won't line up with what you see in the UI.
{% endhint %}

***

## Recommended workflow

Most teams build in sandbox first, then stand up live when they're ready to ship:

1. **Set up sandbox** — domain, products, snippet ID, and (if you verify server-side) a sandbox API key.
2. **Integrate and test** — `sandbox: true`, your sandbox snippet ID, and `p-test-...` product IDs.
3. **Set up live** — production domain, recreate products and pricing, note your live snippet ID and `p-live-...` IDs, and create live API keys.
4. **Ship** — point production traffic at live: remove `sandbox: true` (or set it to `false`), swap in the live snippet ID and product IDs, and use live server credentials.

There is no one-click switch from sandbox to live. Going live means **replacing environment-specific values**; the integration patterns stay the same.

***

## Server-side verification

If your backend calls the tiun API, use the **matching base URL and API key** for the environment your app is using:

| Environment | API base URL                    |
| ----------- | ------------------------------- |
| Live        | `https://api.tiun.live`         |
| Sandbox     | `https://api-sandbox.tiun.live` |

API keys are **not shared** between environments. See the server verification guides for examples.

***

## Agent integration (MCP)

If you use the [tiun MCP server](/guides/agent-integration/agent-integration.md), the agent can read **both** environments from your account — sandbox and live providers are listed separately. With products set up in each environment, the agent can use the correct snippet ID and product IDs for sandbox development versus production, without you copying IDs by hand.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tiun.io/reference/generic/sandbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.