# Instalment plans

An instalment plan splits what a booking owes into a **schedule of dated payments** instead of a
single up-front charge — for example a student paying rent in termly or monthly instalments across
an academic year.

Plans are defined once as **templates** and then applied to bookings through the catalog, so the
same schedule can be reused across many bookings.

> This page explains the concepts and the external `accounting` API surface. Field-level inputs and
> example mutations live in your Postman collection and Apollo — see the
> [AR & Payments API integration](/finance-and-accounting/integrations/ar-payments-api/) page.

## How it fits together

1. You create an **instalment plan template** on a workspace.
2. You **assign** the template to one or more **product groups**.
3. A booking on a product group that has a template **derives its instalment schedule** from that
   template — you read the resulting dates and amounts per booking.

Templates are **workspace-scoped** and assigned to **product groups**, not to bookings directly. A
booking never carries its own bespoke template; its schedule is calculated from the template on its
product group.

## Plan types

A template is one of three kinds:

- **Full payment** — the whole amount in a single instalment (no split).
- **Calendar monthly** — equal monthly instalments across the plan period.
- **Custom** — an explicit list of instalments, each with a period (`from`/`to`) and a
  **percentage** of the total, optionally preceded by **advance payments**.

## Template fields

Key fields on an instalment plan template:

| Field | Meaning |
| --- | --- |
| `workspaceId` | Owning workspace. |
| `name` | Internal name. |
| `externalName` | Guest-facing name (translatable per locale). |
| `type` | Full payment / calendar monthly / custom (see above). |
| `instalmentCount` | Number of instalments the plan produces. |
| `startDate` / `endDate` | Plan period. |
| `academicYear` | Academic year the plan applies to (e.g. `2025/2026` … `2029/2030`). |
| `guarantorRequired` | Whether a guarantor is required for bookings on this plan. |
| `productGroupIds` | Product groups the template is assigned to. |
| `status` | `active` or `expired`. |

## Managing templates

Templates live under the `accounting` namespace:

| Action | API |
| --- | --- |
| Create a template | `accounting.instalmentPlanTemplates.create` |
| Update a template | `accounting.instalmentPlanTemplates.update` |
| Update guest-facing name translations | `accounting.instalmentPlanTemplates.updateExternalNameTranslations` |
| Delete a template | `accounting.instalmentPlanTemplates.delete` |
| Get one template | `accounting.instalmentPlanTemplate(id)` |
| List templates | `accounting.instalmentPlanTemplates(filters)` |

`instalmentPlanTemplates(filters)` requires `workspaceId` and optionally narrows by
`productGroupId`, `status`, and `academicYear`.

## Assigning a template to a product group

Assign and unassign through the catalog:

- `catalog.productGroup.assignInstalmentPlanTemplate`
- `catalog.productGroup.unassignInstalmentPlanTemplate`

(The older `assignProductGroup` / `unassignProductGroup` mutations on the template are deprecated —
prefer the catalog mutations above.)

## Reading a booking's schedule

For a booking on a product group with an assigned template, read the calculated schedule from the
booking:

- `booking.instalmentPlanOptions` — the available plan option(s) for the booking, each exposing its
  instalments as `{ from, to, amount }` plus any advance payments.

Each instalment becomes a **due payment** on the booking as its date arrives. Collection then
follows the normal path — automatically where enabled — described in
[Recurring payment methods (mandates)](/finance-and-accounting/payments/recurring-payment-methods/).

## See also

- [Payments](/finance-and-accounting/payments/) — payment states and automatic collection.
- [Invoices](/finance-and-accounting/document-types/invoices/) — the charges an instalment schedule pays down.