Get future charges

GEThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/contracts/{contract_id}/future_charges

Language

Credentials

Secret key

Instance keyRemember 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

contract_idrequired

cURL request

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

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/future_charges';
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);
}

import requests

url = "https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/future_charges"

headers = {"Authorization": "Basic <base64 of SECRET_KEY:>"}

response = requests.get(url, headers=headers)

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

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

echo $response->getBody();

require 'uri'
require 'net/http'

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

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/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/future_charges"

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

}

const url = 'https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/future_charges';
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN'}};

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/contracts/CONTRACT_ID/future_charges"

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

response = requests.get(url, headers=headers)

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/future_charges', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/future_charges")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN'

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

package main

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

func main() {

  url := "https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/future_charges"

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

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

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

}

Response

List of future charges

{
  "charges": [
    {
      "id": "string",
      "amount": "string",
      "alt_key": "string",
      "charge_number": 0,
      "extra_charge": true,
      "completed": "2026-01-01T12:00:00Z",
      "contract": "string",
      "created": "2026-01-01T12:00:00Z",
      "created_session": "string",
      "due": "2026-01-01T12:00:00Z",
      "initiated": "2026-01-01T12:00:00Z",
      "outstanding_amount": "string",
      "overdue_amount": "string",
      "recurring": true,
      "paid_amount": "string",
      "status": "ACTIVE",
      "updated": "2026-01-01T12:00:00Z",
      "updated_session": "string",
      "writtenoff_amount": "string",
      "v": 0
    }
  ]
}

GET

/contracts/{contract_id}/future_charges

Lists projected future charges for a recurring (frequency-based) contract — up to 3 years or 100 charges ahead. For contracts created with explicit scheduled charges, use List contract charges instead, which returns the concrete charges that were created upfront.

Authorizations

basicAuth
bearerAuth

Parameters

Path Parameters

contract_id

required

string

The contract’s ID (co_...), or the alt_key you gave it.

Responses

200

List of future charges

application/json

object

charges

Array<object>

A charge object representing an invoice on a contract. Contains all information about the charge including its status, amounts, and payment history.

object

string

The ID of the charge

amount

string

The amount of the charge

alt_key

string

Your supplied key for the charge (eg invoice id)

charge_number

integer

Which charge this is in a recurring contract (eg 1 for first, 2 for second)

extra_charge

boolean

If this charge was manually created

completed

string · date-time

When the charge was completed

contract

string

The contract this charge belongs to

created

string · date-time

When the charge was created

created_session

string

The session the object was created by

due

string · date-time

When the charge is due to be paid

initiated

string · date-time

When the charge was instructed

outstanding_amount

string

The amount that remains to be paid

overdue_amount

string

DEPRECATED - do not use

recurring

boolean

If this charge is part of a recurring contract

paid_amount

string

The amount that has been paid

status

string · enum

The status of the charge

Allowed values: ACTIVE PENDING COMPLETED WRITTENOFF

updated

string · date-time

When the charge was last modified

updated_session

string

The session the object was updated by

writtenoff_amount

string

The amount that has been written off

integer

The version of the record

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

Unauthorised: the API key is missing or not valid

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?