# Multi-tenancy / instances

> Shuttle is natively a multi-tenant platform, designed to be used by multiple merchants or business entities. Each tenant in Shuttle is referred to as an instanc

Shuttle is natively a multi-tenant platform, designed to be used by multiple merchants or business entities. Each tenant in Shuttle is referred to as an **instance**.

Instances sit within an [application's](/platforms/embedded-payments/applications/) environments. Each application has a sandbox environment for testing and a live environment for production, each with their own credentials. Within each environment, you create as many instances as you need:

```
Organisation
└── Application
    ├── Sandbox (sandbox credentials)
    │   ├── Instance A
    │   ├── Instance B
    │   └── ...
    └── Live (live credentials)
        ├── Instance A
        ├── Instance B
        └── ...
```

## What is an instance?

An instance is an isolated environment containing a specific payment configuration and all related transaction history. You create one per merchant (or per logical payment context — see below), within either the sandbox or live environment of your application.

## Determining instance granularity

Choosing the right granularity for your instances is a critical decision that depends on your platform's business model:

### Common instance models

| Model | Description | Example Use Case |
|-------|-------------|-----------------|
| One instance per merchant | The most common approach | Standard multi-tenant SaaS platforms |
| Multiple instances per merchant | For merchants needing separate payment configurations | Event platforms with different payment setups per event |
| Object-based instances | Instances tied to specific objects in your data model | Property management systems with one instance per property |
| Configuration-based instances | Reusable payment profiles | Merchants with different payment configurations for corporate vs. consumer events |

### Considerations when choosing instance granularity

- **Financial / legal separation**: Do merchants need payments to clear into different bank accounts?
- **Payment processor requirements**: Do different business units need different payment processors (or merchant accounts)?
- **User experience**: Will merchants understand and navigate multiple payment configurations?

## Working with instances

### Instance keys

Each instance is identified by an **`instance_key`** - a string that uniquely identifies the instance within your application. When choosing an instance key:

- Use a value that makes sense for your business model (client ID, event ID, etc.)
- Ensure it's unique within your application
- Use the same `instance_key` for a merchant in both sandbox and live, so your code doesn't change between them: the credentials you use decide which environment a request goes to
- **Use URL friendly characters only**, eg alphanumeric, underscores, and dashes

### Creating and using instances

1. **Create an instance** using the `POST /instances` API endpoint
2. **Configure payments** via API or using the Merchant Setup component, passing the `instance_key`
3. **Process payments** using the checkout, express checkout, and BNPL messaging components, passing the `instance_key`
4. **Track transactions** in Merchant View, passing the `instance_key`
5. **REST API** - Shuttle's API is structured as `/c/api/instances/{instance_key}/{endpoint}` with the credentials determining the environment
6. **Webhooks** - All webhooks relating to an instance contain the `instance_key`

## API reference

For detailed information on creating and managing instances, see the [Instances API Reference](/platforms/reference/platform/operations/createinstance/).