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