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 instance.

Instances sit within an application's 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
Consider using the same instance_key in both sandbox and live environments for consistency, ideally prefixed with S_ for sandbox and L_ for live so its clear which environment it belongs to
Use URL friendly characters only, eg alphanumeric, underscores, and dashes

Creating and Using Instances

Create an instance using the POST /instances API endpoint
Configure payments via API or using the onboarding component, passing the instance_key
Process payments using the checkout, express checkout, and BNPL messaging components, passing the instance_key
Track transactions in the activity view, passing the instance_key
REST API - Shuttle's api is structured as /c/api/instances/{instance_key}/{endpoint} with the credentials determining the environment
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.