---
title: "List instalment schedules"
method: GET
path: "/instalment_schedules"
tags: ["Instalment Schedule"]
---

# List instalment schedules

`GET /instalment_schedules`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/instalment_schedules`
- Auth: HTTP bearer

Returns a [cursor-paginated](https://docs.gocardless.com/docs/api-reference/data-conventions#cursor-pagination) list of your instalment schedules.

## Query parameters

- `before` string, nullable
- `after` string, nullable
- `limit` union
  - integer
  - string
- `created_at` object
  - `gt` string, date-time: Limit to records created after the specified date-time.
  - `lt` string, date-time: Limit to records created before the specified date-time.
  - `gte` string, date-time: Limit to records created on or after the specified date-time.
  - `lte` string, date-time: Limit to records created on or before the specified date-time.
- `status` string
- `mandate` string: ID of the associated [mandate](https://docs.gocardless.com/docs/api-reference/mandate) which the instalment schedule will create payments against.
- `customer` string: ID of the associated [customer](https://docs.gocardless.com/docs/api-reference/customer).

## Headers

- `GoCardless-Version` string, required

## Response `200`

Successful response

- InstalmentScheduleMultiResourceResponse
  - `instalment_schedules` InstalmentSchedule[]
    - `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)
  - `meta` InstalmentSchedulePaginationMeta: Cursor pagination information
    - `limit` integer, required
    - `cursors` object, required
      - `before` string, nullable, required: Cursor pointing to the end of the desired set.
      - `after` string, nullable, required: Cursor pointing to the start of the desired set.

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