Multi Tenancy / Instances

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

What is an Instance?

An instance in Shuttle is an isolated environment that contains a specific payment configuration and all related transaction history. Instances are a core concept in Shuttle's multi-tenant architecture, allowing you to create separate payment environments for different merchants or business entities.

Instance Architecture

Application: The top-level container in Shuttle's architecture
Environments: Each application has two environments:
- Sandbox: For testing and development
- Live: For production use
Instances: Within each environment, you can create multiple instances

Application
├── Sandbox Environment
│   ├── Instance A
│   ├── Instance B
│   └── Instance C
└── Live Environment
    ├── Instance A
    ├── Instance B
    └── Instance C

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

Best Practices

Plan your instance strategy early in your integration process
Document your instance key schema for future reference
Use descriptive instance keys that align with your business objects
Start with sandbox instances for testing before creating live instances
Consider future scaling when designing your instance architecture

API Reference

For detailed information on creating and managing instances, see the Instances API Reference.