> 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, environment setup, API keys, customers, and analytics. Nothing syncs or carries over automatically between the two.

**Live** is the default: real customers, real payments, your live domain and/or app scheme. `localhost` is blocked in live.

**Sandbox** is for building and testing: simulated payments, test customers, and your development flow. `localhost` works out of the box 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                                                                                        |
| --------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Environment setup (domain / app scheme) | Your live domain (e.g. `yoursite.com`) and/or app scheme (e.g. `myapp://`); no `localhost` | Nothing required — `localhost` works by default; optionally a staging domain and/or app scheme |
| 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.

Payments in sandbox are simulated through Stripe's test mode — nothing is ever charged. For test card numbers, the PayPal simulator, forcing failures, and resetting test state, see the [Simulate payments](/guides/testing/simulate-payments.md) guide.

***

## 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:

* **Sandbox** — the first time you click the **Sandbox** toggle, a dialog asks you to enable it. Click **Enable** — there's nothing to fill in. Then create test products with the same structure you plan to use in live.
* **Live** — in **Settings → Environment setup**, turn on **Web** and enter your live domain, turn on **App** and enter your app scheme, or both. Then create your real product catalog.

Each environment has its own **Environment setup**. You enter one domain and one app scheme yourself; additional domains and app schemes are managed by tiun — contact <support@tiun.io> to add them.

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. **Enable sandbox** — enable it from the sidebar toggle, then create products, copy the snippet ID, and (if you verify server-side) create a sandbox API key.
2. **Integrate and test** — `sandbox: true`, your sandbox snippet ID, and `p-test-...` product IDs.
3. **Set up live** — live domain and/or app scheme in **Settings → Environment setup**, 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.