---
title: "Create (with schedule)"
method: POST
path: "/instalment_schedules/create_with_schedule"
tags: ["Instalment Schedule"]
---

# Create (with schedule)

`POST /instalment_schedules/create_with_schedule`

## Request

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

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](https://docs.gocardless.com/docs/api-reference/instalment-schedule#create-with-schedule).

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.

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `instalment_schedules` object
    - `name` string, required: 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` union, required: 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.
      - string
      - integer
    - `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', required: [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` union: 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).
      - string, nullable
      - integer
    - `payment_reference` string, nullable: An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.<br /> <strong>ACH</strong> - 10 characters<br /> <strong>Autogiro</strong> - 11 characters<br /> <strong>Bacs</strong> - 10 characters<br /> <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12 characters<br /> <strong>Betalingsservice</strong> - 30 characters<br /> <strong>Faster Payments</strong> - 18 characters<br /> <strong>PAD</strong> - scheme doesn't offer references<br /> <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140 characters<br /> Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. <p class='restricted-notice'><strong>Restricted</strong>: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the <a href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise packages</a>.</p> <p class='restricted-notice'><strong>Restricted</strong>: You can not specify a payment reference for Faster Payments.</p>
    - `retry_if_possible` boolean: On failure, automatically retry payments using [intelligent retries](https://docs.gocardless.com/docs/optimise/reduced-failed-payments-with-success-plus). Default is `false`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p>
    - `instalments` object, required: 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)](https://docs.gocardless.com/docs/api-reference/instalment-schedule#create-with-schedule)
      - `start_date` string, date, nullable: The date on which the first payment should be charged. Must be on or after the [mandate](https://docs.gocardless.com/docs/api-reference/mandate)'s `next_possible_charge_date`. When left blank and `month` or `day_of_month` are provided, this will be set to the date of the first payment. If created without `month` or `day_of_month` this will be set as the mandate's `next_possible_charge_date`
      - `interval` integer, required: Number of `interval_units` between charge dates. Must be greater than or equal to `1`.
      - `interval_unit` 'weekly' | 'monthly' | 'yearly', required: The unit of time between customer charge dates. One of `weekly`, `monthly` or `yearly`.
      - `amounts` PaymentAmountStringable[], required: List of amounts of each instalment, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
        - union: Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Minimum and maximum amounts vary by payment scheme. For more information, see [Transaction limits](https://support.gocardless.com/hc/en-gb/articles/115000309245-Transaction-limits) For Variable Recurring Payments (VRP), this must not exceed the mandate's `max_amount_per_payment` constraint.
          - string
          - integer
    - `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.
    - `links` object, required
      - `mandate` string, required: ID of the associated [mandate](https://docs.gocardless.com/docs/api-reference/mandate) which the instalment schedule will create payments against.

## Response `201`

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