Recurring contributions

Recurring contributions fund an Individual's Benefit on a schedule, for example every payday. They have two parts:

• A schedule for the Benefit. setRecurringContributionScheduleForBenefit sets when contributions run. One schedule covers every Individual enrolled in the Benefit.
• An amount for each Individual. setRecurringContributionsForBenefitAndIndividual sets the employee and employer amounts that run on each scheduled date. You can also set them when you enroll the Individual, with employeeRecurringContributionAmount and employerRecurringContributionAmount on enrollIndividualInBenefit.

Contributions run only when both parts exist. Amounts without a schedule are stored but never run. A schedule without amounts runs and contributes nothing.

Recurring contributions are not available for Traditional HRA Benefits, whose recurring contributions come from their coverage levels. Per-Individual amounts are also not available for Benefits with tiered coverage levels.

Set the schedule

Create the schedule before the Benefit's start date. After the Benefit becomes active, you can update its schedule, but you cannot create the first one.

For a Benefit on an Organization with Divisions, set the schedule on the parent Organization's Benefit. It covers the Divisions too. A Division's Benefit id is rejected.

mutation SetRecurringContributionScheduleForBenefit($input: SetRecurringContributionScheduleForBenefitInput!) {
    setRecurringContributionScheduleForBenefit(input: $input) {
        ... on SetRecurringContributionScheduleForBenefitResult {
            benefitId
        }
        ... on BadRequestError {
            code
            message
        }
        ... on InternalServerError {
            code
            message
        }
    }
}

Variables for a schedule that runs every second Friday:

{
    "input": {
        "benefitId": "<benefitId>",
        "schedule": {
            "strategy": "BI_WEEKLY",
            "daysOfWeek": ["FRIDAY"],
            "minRunDate": "2027-01-01"
        }
    }
}

Schedule fields

Which fields you set depends on strategy:

strategy	Required	Not allowed	Runs
WEEKLY	daysOfWeek	dayOfMonth, strategyOption	Every week on each day in daysOfWeek.
BI_WEEKLY	daysOfWeek	dayOfMonth, strategyOption	Every second week on each day in daysOfWeek.
MONTHLY	dayOfMonth (1 to 31)	daysOfWeek	Once a month. Days 29 to 31 move to the last day of shorter months.
SEMI_MONTHLY	strategyOption	daysOfWeek	Twice a month: the 1st and 15th (FIRST_AND_FIFTEENTH), or the 15th and the last day (FIFTEENTH_AND_LAST_DAY).

The other fields:

• minRunDate (required): contributions start on the first scheduled date on or after this date. They also never start before the Benefit's start date.
• skipThirdCycleOfMonth: set it to true for 24 contributions a year instead of 26 ("Biweekly 24"). In a month that has three scheduled dates, the third one is skipped. It works only with BI_WEEKLY and exactly one day in daysOfWeek.
• enablementStatus (on the input, next to schedule): ACTIVE or INACTIVE. It defaults to ACTIVE, so a call that leaves it out turns an inactive schedule back on.

For BI_WEEKLY, the first scheduled date sets which weeks the schedule runs in.

When contributions run

• A scheduled date on a weekend or bank holiday moves to the previous business day. If that day is before today or before the Benefit's start date, the contribution runs on the next business day instead. Because of this rule, a contribution can run a little before minRunDate. For example, a minRunDate that is a Sunday can run on the Friday before.
• Contributions run only on dates between the Benefit's start and end dates.
• An Individual is included on a date only if their enrollment covers that date.

Change or pause a schedule

Call setRecurringContributionScheduleForBenefit again with the new values.

• A new schedule changes only the dates. Each Individual's amounts stay the same, so the same amount runs on each new scheduled date.
• enablementStatus: INACTIVE pauses the schedule. The Individuals' amounts are kept. When you set it back to ACTIVE, contributions continue from the next scheduled date. Dates that passed while the schedule was paused are not made up.

Set an Individual's amounts

mutation SetRecurringContributionsForBenefitAndIndividual($input: SetRecurringContributionsForBenefitAndIndividualInput!) {
    setRecurringContributionsForBenefitAndIndividual(input: $input) {
        ... on SetRecurringContributionsForBenefitAndIndividualResult {
            benefitId
            individualId
        }
        ... on BadRequestError {
            code
            message
        }
        ... on InternalServerError {
            code
            message
        }
    }
}

{
    "input": {
        "benefitId": "<benefitId>",
        "individualId": "<individualId>",
        "employeeRecurringContributionAmount": { "currency": "USD", "lowestDenominationAmount": 5000 },
        "employerRecurringContributionAmount": { "currency": "USD", "lowestDenominationAmount": 2500 }
    }
}

• The Individual must be enrolled in the Benefit, and the Benefit must be pending or active.
• Use the parent Organization's Benefit id. For an Individual in a Division, the amounts apply to their Division's Benefit. A Division's Benefit id is rejected.
• The amounts apply to each scheduled date. If an amount would take the Individual past the Benefit's annual funding limit, the call returns BadRequestError with the limit in the message.
• To read the current amounts, query recurringContribution on the Individual's Account for the Benefit.

Errors

setRecurringContributionScheduleForBenefit returns BadRequestError when:

• A required schedule field is missing, or a field is set that the strategy does not allow.
• skipThirdCycleOfMonth is used with a strategy other than BI_WEEKLY, or with more than one day in daysOfWeek.
• The Benefit is a Traditional HRA Benefit.
• The Benefit is already active and has no schedule.

The message explains what to fix. An unknown benefitId returns InternalServerError.