# Create an instance

`POST https://app.shuttleglobal.com/c/api/instances`

Create a new merchant instance

## Authentication

- basicAuth: Basic Authentication using secret key

## Request body (`application/json`), required

- `instance` (object)
  - `instance_key` (string, required): Your ID for the instance (unique to the application)
  - `name` (string): The name of the instance, typically company name
  - `checkout_urls` (array of string): Domains where you embed the Shuttle checkout widget. Required to enable Apple Pay and Google Pay on those domains. Only list domains where you embed checkout yourself (e.g., your platform pages). Shuttle automatically registers its own hosted pages (payment links, hosted checkout at app.shuttleglobal.com). If you only use Shuttle-hosted payment pages, this field is not needed.
  - `contact_email` (string): The contact email for the instance
  - `contact_name` (string): The contact name for the instance
  - `contact_phone` (string): The contact phone for the instance
  - `country` (string): The country for the instance
  - `legal_entities` (array of object): Enterprise only - an array of legal entities that can receive payment
    - `code` (string, required): Your ID for the entity (alphanumeric _ -, no spaces)
    - `name` (string, required): The name of the entity
    - `country` (string): The 2 digit ISO code of the country in which it is incorporated
  - `merchant_name` (string): The merchant's display name, used for Apple Pay and Click to Pay registration. Falls back to `name` if not set.
  - `receipt_format` (string): Template for generating transaction references. Must contain at least one of: - `#TRANSACTIONKEY#` — a zero-left-padded 8-digit number, incrementing per instance from 10000 (e.g., `00010000`, `00010001`). Not globally unique. - `#TRANSACTIONID#` — the same sequence number (unpadded) prefixed with the instance's client ID (e.g., `1234_10000`). Globally unique. Example: `INV-#TRANSACTIONKEY#` **Note:** Some gateways require transaction references to be unique across all connections. If you are connecting multiple Shuttle instances to the same gateway account, use a unique prefix per instance (e.g., `MERCHANT1-#TRANSACTIONKEY#`) to avoid collisions. Alternatively, use `#TRANSACTIONID#` which is globally unique and requires no prefix. Some gateways also impose a maximum length on transaction references. If the formatted reference exceeds the gateway's limit, it will be front-trimmed -- only the trailing characters are kept. Keep this in mind when designing long prefixes.
  - `secret_key` (string): Generates a per-instance API key that allows the merchant to authenticate directly against their instance without requiring the platform's application credentials. Set to `"NEW"` to auto-generate a key. On update: pass `"NEW"` to rotate the key, `false` or `""` to clear it, or `true` to leave the existing key unchanged.
  - `tcs_accepted` (boolean): True if the user manually accepted the T&Cs - do not populate this unless you have collected proof of this

## Responses

### 200: Successful operation

```json
{
  "instance": {
    "id": "string",
    "name": "string",
    "instance_key": "string",
    "status": "ACTIVATING",
    "application": "string",
    "checkout_urls": [
      "string"
    ],
    "client": "string",
    "contact_email": "string",
    "contact_name": "string",
    "contact_phone": "string",
    "country": "string",
    "created": "2026-01-01T12:00:00Z",
    "domain": "string",
    "domains": [
      "string"
    ],
    "environment": "SANDBOX",
    "features": [
      "string"
    ],
    "last_contract": "2026-01-01T12:00:00Z",
    "last_transaction": "2026-01-01T12:00:00Z",
    "merchant_name": "string",
    "metadata": {},
    "parent": "string",
    "private_integrations": [
      "string"
    ],
    "processors": [
      "string"
    ],
    "receipt_format": "string",
    "receipt_users": [
      "string"
    ],
    "report_users": [
      "string"
    ],
    "retry_error_schedule": [
      0
    ],
    "retry_schedule": [
      0
    ],
    "secret_key": "string",
    "tcs_accepted": "2026-01-01T12:00:00Z",
    "tcs_accepted_user": "string",
    "tcs_outstanding": true,
    "terminated": "2026-01-01T12:00:00Z",
    "updated": "2026-01-01T12:00:00Z",
    "v": 0,
    "webhook_target": "string"
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorized

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/platform/operations/createinstance/