List instances

GEThttps://app.shuttleglobal.com/c/api/instances

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

Query

criteriaorderexpandlimitoffset

cURL request

curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'

const url = 'https://app.shuttleglobal.com/c/api/instances';
const options = {method: 'GET', headers: {Authorization: 'Basic <base64 of SECRET_KEY:>'}};

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

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/instances', [
  'headers' => [
    'Authorization' => 'Basic <base64 of SECRET_KEY:>',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'

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

package main

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

func main() {

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

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Basic <base64 of SECRET_KEY:>")

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

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

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

}

Response

Successful operation

{
  "instances": [
    {
      "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"
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

GET

/instances

Performs a search against instance objects with optional filtering, sorting, and pagination.

Authorizations

basicAuth

Parameters

Query Parameters

criteria

string

The search criteria (URL encoded). Available fields: application, client, contact_email, contact_name, contact_phone, created, domain, id, last_contract, last_transaction, name, status, updated

Supports the following operators:

=: Exact match, separate multiple values with ; for IN operation
!=: Not equal
>=, >, <, <=: Greater than/equal, less than/equal
~=: Partial match (case insensitive)
<>: Between, separate values with ; (e.g., <>min;max)
!: Is null
!!: Is not null

Separate multiple criteria with commas (,)

Notes:

Strings are case insensitive (with some exceptions)
Booleans are Y/N (TIP: check for =Y or !=Y as some objects treat false as null)

Examples:

status=ACTIVE;FAILING (status is either ACTIVE or FAILING)
status=ACTIVE;FAILING,email=dave@gmail.com (status is ACTIVE or FAILING AND email is dave@gmail.com)
name~=Test (name contains ‘Test’)
created<>2023-01-01;2023-12-31 (created between Jan 1 and Dec 31, 2023)
scheduler=Y (scheduler is enabled)

order

string

The sort order to apply. Format: field[:desc][,field2[:desc]]

Supports any field that criteria supports
Defaults to created:desc if not specified
Will order ascending unless you specify desc
Separate multiple order fields with commas

Examples:

order=updated (sort by updated ascending)
order=updated:desc (sort by updated descending)
order=status,updated:desc (sort by status ascending, then updated descending)

expand

string

Fields to expand into full objects

limit

integer

default 20

Number of records to return: 20 if not set, at most 1000.

offset

integer · 0

Number of records to skip before the first one returned. offset + limit can’t exceed 5000; to read further, page by a field such as created instead. See Paging through results.

Responses

200

Successful operation

application/json

object

instances

Array<object>

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

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.

meta

object

limit

integer

The limit used for the query

offset

integer

The offset used for the query

total

integer

The total number of records matching the query

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

Was this page helpful?