Update an instance

PUThttps://app.shuttleglobal.com/c/api/instances/{instance_id}

Language

Credentials

Secret key

Remember on this device

Kept in this browser tab unless you tick Remember; don't on a shared computer. Use keys from a sandbox account to test without moving money.

Parameters

Path

instance_idrequired

Body application/json

cURL request

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 '{}'

const url = 'https://app.shuttleglobal.com/c/api/instances/INSTANCE_ID';
const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Basic <base64 of SECRET_KEY:>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://app.shuttleglobal.com/c/api/instances/INSTANCE_ID"

payload = {}
headers = {
    "Authorization": "Basic <base64 of SECRET_KEY:>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://app.shuttleglobal.com/c/api/instances/INSTANCE_ID', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <base64 of SECRET_KEY:>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/instances/INSTANCE_ID")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://app.shuttleglobal.com/c/api/instances/INSTANCE_ID"

  payload := strings.NewReader("{}")

  req, _ := http.NewRequest("PUT", url, payload)

  req.Header.Add("Authorization", "Basic <base64 of SECRET_KEY:>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Response

Successful operation

{
  "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"
  }
}

PUT

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

Authorizations

basicAuth

Parameters

Path Parameters

instance_id

required

string

The instance’s ID (cl_...), or the instance_key you gave it.

Request Body^required

application/json

object

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<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<object>

Enterprise only - an array of legal entities that can receive payment

object

code

required

string

Your ID for the entity (alphanumeric _ -, no spaces)

name

required

string

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

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.

Responses

200

Successful operation

application/json

object

instance

object

string

Shuttle’s ID for the instance (globally unique)

name

string

The name of the instance, typically company name

instance_key

string

Your ID for the instance (unique to the application)

status

string · enum

The status of the instance, typically ACTIVE or INACTIVE

Allowed values: ACTIVATING ACTIVE INACTIVE

application

string

The application the instance was created in

checkout_urls

Array<string>

Domains where you embed the Shuttle checkout widget, used for Apple Pay and Google Pay domain registration.

client

string

The internal Shuttle ID for this instance

contact_email

string

The contact email provided for the instance, used when providing support

contact_name

string

The contact name provided for the instance, used when providing support

contact_phone

string

The contact phone provided for the instance, used when providing support

country

string

The country provided for the instance

created

string · date-time

The date the instance was created

domain

string

The custom domain for this instance

domains

Array<string>

A list of domains this instance is available under

environment

string · enum

Either SANDBOX or LIVE

Allowed values: SANDBOX LIVE

features

Array<string>

Enterprise only features

last_contract

string · date-time

The date of last contract creation

last_transaction

string · date-time

The date of last transaction creation

merchant_name

string

The merchant’s display name

metadata

object

A map of user defined key value pairs

object

parent

string

The parent instance ID

private_integrations

Array<string>

Any private processors that have been made available to this instance

processors

Array<string>

A list of connected processors

receipt_format

string

Template for generating transaction references. Contains #TRANSACTIONKEY# or #TRANSACTIONID#.

receipt_users

Array<string>

Enterprise only

report_users

Array<string>

Enterprise only

retry_error_schedule

Array<integer>

Custom retry schedule for errored payments (array of delays in milliseconds)

retry_schedule

Array<integer>

Custom retry schedule for declined payments (array of delays in milliseconds)

secret_key

string

Per-instance API key for direct merchant authentication. Only returned when expand=secret_key is requested.

tcs_accepted

string · date-time

If the user manually accepted the T&Cs, the date they were accepted

tcs_accepted_user

string

The user_id of the user that accepted the terms and conditions

tcs_outstanding

boolean

True if the user is required to accept the terms and conditions

terminated

string · date-time

The date the instance was terminated (status INACTIVE only)

updated

string · date-time

The date the instance was last updated

integer

The version of the record

webhook_target

string

400

Bad request

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

401

Unauthorized

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

Example

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

404

Instance not found

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

Was this page helpful?

Update an instance

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

400

401

404

Request Body^required