GoCardless Instalment Schedules API.
Fixed payment plans that automatically create a series of payments against a mandate. Two creation modes are supported:
- With dates — you specify exact charge dates and amounts for each instalment.
- With schedule — you specify an interval and GoCardless calculates the dates.
Example — create with explicit dates
{:ok, schedule} = GoCardlessClient.Resources.InstalmentSchedules.create_with_dates(
client,
%{
name: "3-month plan",
currency: "GBP",
instalments: [
%{charge_date: "2025-02-01", amount: 5000},
%{charge_date: "2025-03-01", amount: 5000},
%{charge_date: "2025-04-01", amount: 5000}
],
links: %{mandate: "MD123"}
}
)Example — create with schedule
{:ok, schedule} = GoCardlessClient.Resources.InstalmentSchedules.create_with_schedule(
client,
%{
name: "6-month plan",
currency: "GBP",
amount: 3000,
start_date: "2025-02-01",
count: 6,
interval_unit: "monthly",
interval: 1,
links: %{mandate: "MD123"}
}
)Summary
Functions
Cancels an instalment schedule and all its pending payments.
Eagerly collects all instalment schedules into a list.
Creates an instalment schedule with explicit charge dates.
Creates an instalment schedule from an interval-based recurrence rule.
Retrieves a single instalment schedule by ID.
Returns a page of instalment schedules.
Returns a lazy Stream over all pages of instalment schedules.
Updates an instalment schedule. Only :name and :metadata can be changed.
Functions
@spec cancel(GoCardlessClient.Client.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Cancels an instalment schedule and all its pending payments.
@spec collect_all(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, [map()]} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Eagerly collects all instalment schedules into a list.
@spec create_with_dates(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Creates an instalment schedule with explicit charge dates.
Params
:name— schedule name (required):currency— ISO 4217 currency code (required):instalments— list of%{charge_date: "YYYY-MM-DD", amount: integer}maps (required):total_amount— must match sum of instalment amounts (optional safety check):app_fee— app fee per payment in minor units (partner integrations):metadata— key-value pairslinks.mandate— Mandate ID (required)
@spec create_with_schedule(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Creates an instalment schedule from an interval-based recurrence rule.
Params
:name— schedule name (required):currency— ISO 4217 (required):amount— amount per instalment in minor units (required):start_date— first payment date"YYYY-MM-DD"(required):count— total number of payments (required):interval_unit—"weekly","monthly", or"yearly"(required):interval— e.g.1for monthly,2for bi-monthly (required):day_of_month— day of month for monthly/yearly (optional):month— month for yearly schedules e.g."january"(optional):app_fee— per-payment app fee (partner integrations)links.mandate— Mandate ID (required)
@spec get(GoCardlessClient.Client.t(), String.t(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Retrieves a single instalment schedule by ID.
@spec list(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, %{items: [map()], meta: map()}} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Returns a page of instalment schedules.
Filter by :mandate, :status (pending, active, creation_failed,
completed, cancelled, errored).
@spec stream(GoCardlessClient.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy Stream over all pages of instalment schedules.
@spec update(GoCardlessClient.Client.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Updates an instalment schedule. Only :name and :metadata can be changed.