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
accountingAPI surface. Field-level inputs and example mutations live in your Postman collection and Apollo — see the AR & Payments API integration page.
How it fits together
Section titled “How it fits together”- You create an instalment plan template on a workspace.
- You assign the template to one or more product groups.
- 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
Section titled “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
Section titled “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
Section titled “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
Section titled “Assigning a template to a product group”Assign and unassign through the catalog:
catalog.productGroup.assignInstalmentPlanTemplatecatalog.productGroup.unassignInstalmentPlanTemplate
(The older assignProductGroup / unassignProductGroup mutations on the template are deprecated —
prefer the catalog mutations above.)
Reading a booking’s schedule
Section titled “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).