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

# Create (with dates)

`POST /instalment_schedules/create_with_dates`

## Request

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

Creates a new instalment schedule object, along with the associated payments. This
API is recommended if you know the specific dates you wish to charge. Otherwise,
please check out the [scheduling version](https://docs.gocardless.com/docs/api-reference/instalment-schedule#create-with-schedule).

The `instalments` property is an array of payment properties (`amount` and
`charge_date`).

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: An explicit array of instalment payments, each specifying at least an `amount` and `charge_date`. See [create (with dates)](https://docs.gocardless.com/docs/api-reference/instalment-schedule#create-with-schedule)
      - `amount` union, required: 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
      - `charge_date` string, date, nullable, required: A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the [mandate](https://docs.gocardless.com/docs/api-reference/mandate), it will be automatically rolled forwards to that date.
      - `description` string, nullable: A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see [compliance requirements](https://docs.gocardless.com/docs/api-reference/compliance-requirements)).
    - `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)