Cancel a contract

POSThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/contracts/{contract_id}/cancel

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

Body application/json

cURL request

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

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/cancel';
const options = {
  method: 'POST',
  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/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/cancel"

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

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/cancel', [
  '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/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/cancel")

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

request = Net::HTTP::Post.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/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/cancel"

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

  req, _ := http.NewRequest("POST", 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))

}

curl --request POST \
  --url https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/cancel \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

const url = 'https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/cancel';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN', '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/contracts/CONTRACT_ID/cancel"

payload = {}
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.shuttleglobal.com/c/api/contracts/CONTRACT_ID/cancel', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN'
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/contracts/CONTRACT_ID/cancel"

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

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

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
  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

Updated contract

{
  "contract": {
    "account": "string",
    "alt_key": "string",
    "amount": "string",
    "channel": "string",
    "completed": "2026-01-01T12:00:00Z",
    "created": "2026-01-01T12:00:00Z",
    "currency": "string",
    "description": "string",
    "designation": "string",
    "frequency": "WEEKLY",
    "gateway": "string",
    "id": "string",
    "initiated": "2026-01-01T12:00:00Z",
    "initiative": "string",
    "keep_active_until": "2026-01-01T12:00:00Z",
    "last_charge": "string",
    "last_transaction": "string",
    "legal_entity": "string",
    "metadata": {
      "order_id": "12345",
      "customer_reference": "CUS-001"
    },
    "next_contract": "string",
    "next_payment": "2026-01-01T12:00:00Z",
    "nonce": "string",
    "account_alt_key": "string",
    "charge_count": 0,
    "event_date": "2026-01-01T12:00:00Z",
    "outstanding_amount": "string",
    "payment_method": "string",
    "recurring": true,
    "retry_complete": true,
    "retry_count": 0,
    "status": "SETUP",
    "updated": "2026-01-01T12:00:00Z"
  }
}

POST

/contracts/{contract_id}/cancel

Cancelling a contract will prevent future charges being created on a contract and stop all automated payments. A contract may still have an outstanding balance at time of cancellation.

Authorizations

basicAuth
bearerAuth

Parameters

Path Parameters

contract_id

required

string

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

Request Body^required

application/json

object

write_off

boolean

If any outstanding amount should be written off. If not and there’s an outstanding amount, the contract will transition to CANCELLING status

cancel_retries

boolean

If automatic retries should be stopped for any outstanding amount. This will set next_payment to blank

strict

boolean

If true, reject the cancellation when a transaction is in progress on the contract. Use when you need certainty that no further payment will be allocated after cancellation. Defaults to false, in which case the cancellation proceeds and any in-progress transaction resolves independently.

Responses

200

Updated contract

application/json

object

contract

object

A contract representing a one-time or recurring payment agreement

object

account

string

Associated account ID

alt_key

string

Your reference for the contract

amount

string

Contract amount

channel

string

Channel ID

completed

string · date-time

When the contract was completed

created

string · date-time

When the contract was created

currency

string

Currency code

description

string

Description passed to the payment API

designation

string

Designation ID

frequency

string · enum

Payment frequency for recurring contracts

Allowed values: WEEKLY FORTNIGHTLY BIMONTHLY MONTHLY QUARTERLY BIANNUALLY ANNUALLY

gateway

string

Payment gateway ID

string

Contract ID

initiated

string · date-time

When the contract was initiated

initiative

string

Initiative ID

keep_active_until

string · date-time

Optional. When set to a future date, the contract stays active until this date even after its final scheduled payment is collected, so mid-term amendments can still be applied. Once the date has passed and no balance is outstanding, the contract completes normally. Omitted when not set.

last_charge

string

ID of the last charge

last_transaction

string

ID of the last transaction

legal_entity

string

Legal entity ID

metadata

object

e.g. { "order_id": "12345", "customer_reference": "CUS-001"}

Custom key-value pairs stored on the contract

object

key

additional properties

string

next_contract

string

ID of the successor contract (created when amount or frequency is changed)

next_payment

string · date-time

When the next payment will be attempted

nonce

string

Unique identifier for duplicate payment prevention. If the same nonce is submitted within 24 hours:

No new contract will be created
The success status of the previous contract will be returned

account_alt_key

string

Your identifier for the account on this contract

charge_count

integer

Number of charges raised on this contract

event_date

string · date-time

Event date associated with the payment

outstanding_amount

string

Amount remaining to be paid

payment_method

string

Payment method ID

recurring

boolean

Whether this is a recurring contract

retry_complete

boolean

Whether retry attempts are exhausted

retry_count

integer

Number of retry attempts made

status

string · enum

Current contract status

Allowed values: SETUP ACTIVE FAILING PENDING SUSPENDED UNRESOLVED COMPLETED CANCELLED CANCELLING

updated

string · date-time

When the contract was last modified

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?

Cancel a contract

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

400

401

Request Body^required