# Instalment Schedule Source: https://docs.gocardless.com/docs/api-reference/instalment-schedule ## Create (with schedule) `POST /instalment_schedules` Creates a new instalment schedule object, along with the associated payments. This API is recommended if you wish to use the GoCardless scheduling logic. For finer control over the individual dates, please check out the [alternative version](#instalment-schedules-create-with-dates). It can take quite a while to create the associated payments, so the API will return the status as `pending` initially. When processing has completed, a subsequent GET request for the instalment schedule will either have the status `success` and link to the created payments, or the status `error` and detailed information about the failures. ### Request body Wrap request body attributes in a `instalment_schedules` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | No | 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. | | `total_amount` | string / integer | No | 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. | | `currency` | string | No | [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. | | `app_fee` | string / integer | No | The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). | | `payment_reference` | string | No | An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

| | `retry_if_possible` | boolean | No | On failure, automatically retry payments using [intelligent retries](/success-plus/overview). Default is `false`.

Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).

| | `instalments` | object | No | Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See [create (with schedule)](#instalment-schedules-create-with-schedule) | | `metadata` | object | No | 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. | | `links` | object | No | | ### Responses | Status | Description | | --- | --- | | 201 | Resource created successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## List instalment schedules `GET /instalment_schedules` Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your instalment schedules. ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Get a single instalment schedule `GET /instalment_schedules/{instalment_schedule_id}` Retrieves the details of an existing instalment schedule. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `instalment_schedule_id` | path | string | Yes | The instalment schedule id | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Update an instalment schedule `PUT /instalment_schedules/{instalment_schedule_id}` Updates an instalment schedule. This accepts only the metadata parameter. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `instalment_schedule_id` | path | string | Yes | The instalment schedule id | ### Request body Wrap request body attributes in a `instalment_schedules` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Cancel an instalment schedule `POST /instalment_schedules/{instalment_schedule_id}/actions/cancel` 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `instalment_schedule_id` | path | string | Yes | The instalment schedule id | ### Request body Wrap request body attributes in a `instalment_schedules` object. | Field | Type | Required | Description | | --- | --- | --- | --- | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error |