# Update an instance

`PUT https://app.shuttleglobal.com/c/api/instances/{instance_id}`

Update an existing instance. Only the passed fields will be updated, fields not passed will not be updated. To blank a field, pass the field with an empty string.

## Authentication

- basicAuth: Basic Authentication using secret key

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | string | yes | The instance's ID (`cl_...`), or the `instance_key` you gave it. |

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

- `instance` (object)
  - `instance_key` (string): If you want to update the instance key from that in the URL
  - `name` (string): The name of the instance
  - `application` (string): If you want to change the application this instance belongs to
  - `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. Shuttle automatically registers its own hosted pages.
  - `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#` — zero-left-padded 8-digit number, incrementing per instance from 10000 (e.g., `00010000`). Not globally unique. - `#TRANSACTIONID#` — the same sequence number (unpadded) prefixed with the client ID (e.g., `1234_10000`). Globally unique. If connecting multiple instances to the same gateway account, use a unique prefix per instance or use `#TRANSACTIONID#` to avoid reference collisions. If the formatted reference exceeds a gateway's length limit, it will be front-trimmed.
  - `secret_key` (string): Rotate or clear the per-instance API key. Pass `"NEW"` to generate a new 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 - you can only modify this to true and not back again
  - `v` (integer): The version of the record for optimistic concurrency control
  - `webhook_target` (string): The webhook target URL for this instance. Replaces the application-level webhook destination for this instance -- events are not sent to both. Supports retry, failover, and fan-out configuration. See [Webhook Destinations](/platforms/reference/webhooks/#webhook-destinations).

## 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"
}
```

### 404: Instance not found

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

## Example request

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

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