Step 11 – Set Up Installments

UpdatePaymentPlanInstalments

This API allows you to create, update, or delete rent payment instalment configurations under a payment plan. It supports both full-payment and installment-based rent collection based on the guest’s tenancy length.

Instalment

Create instalment

API: updatePaymentPlanInstalments
Purpose & Use Cases This API allows landlords to configure how guests pay their rent based on the length of their stay. For short-term stays, landlords may choose to collect rent in full upfront via Student.com. For long-term stays, installment payment options can be offered.

You can define tenancy length tiers (e.g., ≤18 weeks, >18 weeks) and specify different rent payment rules for each tier. These include:
- Full Payment: Guests pay the entire rent to Student.com at the time of booking confirmation.
- Rental Installments: Guests pay part of the rent to Student.com , and the remaining balance directly to the landlord in defined intervals.
When rentalInstallments and requireGuarantor are both set to true, the country field must specify the applicable guarantor region (e.g., “United Kingdom”). If no guarantor location is required, the country field can be omitted.

You can also define how subsequent payments are made directly to the landlord using the following frequency options: allAtOnce, quarterly, monthly, and weekly. These settings should be communicated to the guest, as payment will occur outside of the platform after booking confirmation.
Validation Rules: (Business Logic)

Tenancy tiers must start from 0 and be continuous (no gaps or overlaps).
Tenancy tiers must end with an open-ended value (infinity).
The number of rentPaymentOptions tiers cannot exceed 6.
Each tier must be sorted by fromTenancyStart in ascending order.
Each object in rentPaymentOptions must belong to the same paymentPlanId.
fullPayment and rentalInstallments cannot both be set to false.
If rentalInstallments is false, fields like allAtOnce, quarterly, monthly, weekly, payNowAmount, and requireGuarantor must be null.
If rentalInstallments is true and paymentOnline is not false, the above fields must not be null.
If payNowAmount is set, it must be a value greater than 0 and less than the total duration of the tier.
quarterly payments are invalid for tenancy tiers of 12 weeks or less.
monthly payments are invalid for tenancy tiers of 4 weeks or less.
If requireGuarantor is false, the country field must be null.

Request:

Attribute Name	Data Type	Required	Details
paymentPlanId	DecodedPaymentPlanID	Yes	ID of the payment plan related to the instalment
rentPaymentOptions	rentPaymentOptions[]	No	Option list of rent payment; rentPaymentOptions is an object includes, id: DecodedOrderInstalmentID, fromTenancyStart: Int!, toTenancyEnd: Int, tenancyUnit: TenancyUnit, fullPayment: Boolean, rentalInstallments: Boolean, payNowAmount: Float, quarterly: Boolean, monthly: Boolean, weekly: Boolean, allAtOnce: Boolean, requireGuarantor: Boolean, country: String;

  QUERY
mutation UpdatePaymentPlanInstalments($input: UpdatePaymentPlanInstalmentsInput) {
  updatePaymentPlanInstalments(input: $input) {
    orderInstalments {
      id
      paymentPlanId
      name
      fromTenancy
      toTenancy
      tenancyUnit
      fullPayment
      payNowAmount
      payWeekly
      payRemainderAtOnce
      payQuarterly
      payMonthly
      requireGuarantor
      country {
        id
        name
        countryCode
        currency
        rentCycle
      }
      updatedAt
      createdAt
    }
  }
}

GRAPHQL VARIABLES
{
    "input": {
        "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTM2fQ",
        "rentPaymentOptions": [
            {
                "fromTenancyStart": 0,
                "toTenancyEnd": 18,
                "payNowAmount": 1,
                "tenancyUnit": "WEEKS",
                "requireGuarantor": true,
                "fullPayment": true,
                "rentalInstallments": true,
                "allAtOnce": true,
                "quarterly": null,
                "monthly": null,
                "weekly": null
            },
            {
                "fromTenancyStart": 18,
                "toTenancyEnd": null,
                "payNowAmount": 4,
                "tenancyUnit": "WEEKS",
                "requireGuarantor": true,
                "fullPayment": true,
                "rentalInstallments": true,
                "allAtOnce": true,
                "quarterly": true,
                "monthly": null,
                "weekly": null
            }
        ]
    }
}

Response:

  {
    "data": {
        "updatePaymentPlanInstalments": {
            "orderInstalments": [
                {
                    "id": "eyJ0eXBlIjoiT3JkZXJJbnN0YWxtZW50IiwiaWQiOjExNn0=",
                    "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTM2fQ==",
                    "name": null,
                    "fromTenancy": 0,
                    "toTenancy": 18,
                    "tenancyUnit": "WEEKS",
                    "fullPayment": true,
                    "payNowAmount": 1,
                    "payWeekly": null,
                    "payRemainderAtOnce": true,
                    "payQuarterly": null,
                    "payMonthly": null,
                    "requireGuarantor": true,
                    "country": null,
                    "updatedAt": "2025-06-19T06:25:41+00:00",
                    "createdAt": "2025-06-19T06:25:41+00:00"
                },
                {
                    "id": "eyJ0eXBlIjoiT3JkZXJJbnN0YWxtZW50IiwiaWQiOjExN30=",
                    "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTM2fQ==",
                    "name": null,
                    "fromTenancy": 18,
                    "toTenancy": null,
                    "tenancyUnit": "WEEKS",
                    "fullPayment": true,
                    "payNowAmount": 4,
                    "payWeekly": null,
                    "payRemainderAtOnce": true,
                    "payQuarterly": true,
                    "payMonthly": null,
                    "requireGuarantor": true,
                    "country": null,
                    "updatedAt": "2025-06-19T06:25:41+00:00",
                    "createdAt": "2025-06-19T06:25:41+00:00"
                }
            ]
        }
    }
}

Error Message:

Error Message	Description
Tenancy tiers exceed the max limit on tenancy tiers	Unable to update the payment plan instalments because tenancyTiers.length > `6`
Tenancy tiers must start from 0	Unable to update the payment plan instalments because tenancyTiers[p1].fromTenancyStart !== `0`
Tenancy tier fromTenancy cannot greater than or equals to toTenancy	Tenancy tier fromTenancy cannot greater than or equals to toTenancy
Tenancy tiers are not continuous	tenancyTiers[p1].toTenancyEnd !== tenancyTiers[p2].fromTenancyStart
payNowToStcom should be greater than 0	Unable to update the payment plan instalments because payNowToStcom <= `0`
Tenancy tiers must end with infinite	Unable to update the payment plan instalments because the last tier does not end with infinity
OrderInstallments don’t belong to the same PaymentPlan	Unable to update the payment plan instalments because the OrderInstallments don’t belong to the same PaymentPlan
fullPayment and rentalInstallment cannot be false at the same time	Unable to proceed because both fullPayment and rentalInstallment cannot be `false` simultaneously
rentalInstallment is false, rentalInstallment fields must be nullable	Unable to proceed because when rentalInstallment is `false`, the following fields must be `null`: payNowToStcom quarterly monthly weekly allAtOnce requireGuarantor
rentalInstallment is true, rentalInstallment fields must be non-nullable	Unable to proceed because when rentalInstallment is `true` and paymentPlan.category = `RENT_IS_REQUIRED` and paymentPlan.paymentOnline !== `false`, the following fields must not be`null`: payNowToStcom quarterly monthly weekly allAtOnce requireGuarantor
payNowToStcom must be more than 0 and less than the upper limit of this tier	Unable to proceed because payNowToStcom must be greater than `0` and less than the calculated upper limit of the tier, based on item.tenancyUnit and item.toTenancyEnd
payQuarterly option is not available for tier less than or equal to 12 weeks	Unable to proceed because the payQuarterly option cannot be selected for tiers with a duration of 12 weeks or less
payMonthly option is not available for tier less than or equal to 4 weeks	Unable to proceed because the payMonthly option cannot be selected for tiers with a duration of 4 weeks or less
requireGuarantor is false; country is null	Unable to proceed because when requireGuarantor is `false`, the country field must be `null`
paymentPlan’s paymentOnline is false, allAtOnce of rentalInstallment is null	Unable to proceed because when paymentPlan.paymentOnline is `false`, the allAtOnce field of rentalInstallment must be `null` This condition applies when: paymentPlan.category = `RENT_IS_REQUIRED` rentalInstallment = `true` The following fields are also `null`: payNowToStcom quarterly monthly weekly requireGuarantor

OrderInstalment Object

Attribute Name	Data Type	Details
id	ID	ID of the payment plan this instalment configuration belongs to
paymentPlanId	ID	The ID of the payment plan this instalment is linked to
name	String	Name of the instalment
fromTenancy	Int	Start of the tenancy tier (in weeks); Must begin at 0
toTenancy	Int	End of the tenancy tier (in weeks). Cannot be less than or equal to fromTenancyStart
tenancyUnit	TenancyUnit	Unit of tenancy duration; Possible values: `DAYS` `WEEKS` `MONTHS`
fullPayment	Boolean	If `true`, guests must pay full rent via Student.com. Cannot be `false` if rentalInstallments is also `false`.
payNowAmount	Float	Amount of pay now
payWeekly	Boolean	Indicate whether to pay weekly
payQuarterly	Boolean	Indicate whether to pay quarterly
payMonthly	Boolean	Indicate whether to pay monthly
payRemainderAtOnce	Boolean	Indicate whether the remaining rent (after any initial payment) should be paid in a single lump sum
requireGuarantor	Boolean	Indicate whether guarantor is required for instalment plans
country	Country	Required only when requireGuarantor is `true`. Leave it blank if not required; Country is an object includes, id: ID!, name: String!, countryCode: String!, currency: String!, rentCycle: BillingCycle!; BillingCycle has possible values: `DAILY` `WEEKLY` `MONTHLY`
createdAt	Datetime	The created time of the instalment in format (YYYY-MM-DDTHH:mm:ssZ)
updatedAt	Datetime	The updated time of the instalment in format (YYYY-MM-DDTHH:mm:ssZ)

Step 10 – Set Up Order Fee

Step 12 – Set up Payouts / Payment Methods

Step 11 – Set Up Installments

UpdatePaymentPlanInstalments link

OrderInstalment Object link

UpdatePaymentPlanInstalments

OrderInstalment Object