---
title: "Cancel an instalment schedule"
method: POST
path: "/instalment_schedules/{instalment_schedule_id}/actions/cancel"
tags: ["Instalment Schedule"]
---

# Cancel an instalment schedule

`POST /instalment_schedules/{instalment_schedule_id}/actions/cancel`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/instalment_schedules/{instalment_schedule_id}/actions/cancel`
- Auth: HTTP bearer

Immediately cancels an instalment schedule; no further payments will be collected for it.

This will fail with a `cancellation_failed` error if the instalment schedule is already cancelled or has completed.

## Path parameters

- `instalment_schedule_id` string, required

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `instalment_schedules` object

## Response `200`

Action completed successfully

- InstalmentScheduleSingleResourceResponse
  - `instalment_schedules` InstalmentSchedule: Instalment schedules are objects which represent a collection of related payments, with the intention to collect the `total_amount` specified. The API supports both schedule-based creation (similar to subscriptions) as well as explicit selection of differing payment amounts and charge dates. Unlike subscriptions, the payments are created immediately, so the instalment schedule cannot be modified once submitted and instead can only be cancelled (which will cancel any of the payments which have not yet been submitted). Customers will receive a single notification about the complete schedule of collection.
    - `id` string: Unique identifier, beginning with "IS".
    - `created_at` string, date-time: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `total_amount` integer: The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
    - `name` string: Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
    - `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD': [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
    - `metadata` CustomerMetadata: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
    - `status` 'pending' | 'active' | 'creation_failed' | 'completed' | 'cancelled' | 'errored': One of: - `pending`: we're waiting for GC to create the payments - `active`: the payments have been created, and the schedule is active - `creation_failed`: payment creation failed - `completed`: we have passed the date of the final payment and all payments have been collected - `cancelled`: the schedule has been cancelled - `errored`: one or more payments have failed
    - `payment_errors` InstalmentSchedulePaymentErrors: If the status is `creation_failed`, this property will be populated with validation failures from the individual payments, arranged by the index of the payment that failed.
    - `links` InstalmentScheduleLinks: Links to associated objects
      - `mandate` string, required: ID of the associated [mandate](https://docs.gocardless.com/docs/api-reference/mandate) which the instalment schedule will create payments against.
      - `customer` string, required: ID of the associated [customer](https://docs.gocardless.com/docs/api-reference/customer).
      - `payments` string[]: Array of IDs of the associated [payments](https://docs.gocardless.com/docs/api-reference/payment)

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)