Skip to main content

Benefit funding method

The funding method of a Benefit controls how money moves into the Benefit's account: when First Dollar pulls it from the bank account that funds the Benefit, and how much. You can read the funding method and change it through the Partner API.

OperationUse it to
benefitRead the funding method of a Benefit, in its fundingConfiguration field.
benefitTemplatesRead the funding defaults that a template gives to new Benefits.
updateBenefitFundingMethodChange the funding method of a Benefit.

These operations change settings only. They do not move money, and they do not link a bank account. To credit the account of one Individual, use fundBenefitForIndividual.

Funding methods​

MethodSettingsWhat it does
RMFbalanceFundingAlgorithm: RMF, with rmfKeeps the balance of the Benefit's account above a threshold, on the RMF schedule.
Claims-basedbalanceFundingAlgorithm: NONE, with claimFunding.enabled: trueFunds each approved claim, on the claims funding schedule.
RMF and claims-basedbalanceFundingAlgorithm: RMF, with claimFunding.enabled: trueDoes both.
NonebalanceFundingAlgorithm: NONE, with claims funding off or absentFirst Dollar does not fund the Benefit automatically.

RMF is Required Minimum Funding. An RMF threshold of 0 funds approved claims and spend on the next RMF run.

FULL_COMMITMENT and CONTRIBUTION_BASED can appear as the balanceFundingAlgorithm when you read a Benefit. You cannot set them through the Partner API. You cannot change the balanceFundingAlgorithm of an HSA Benefit.

Benefits with cards​

Card spend draws on the same funds that claims funding pulls. For this reason, a Benefit with cards can use claims funding only together with RMF.

  • On a Benefit without cards, you can use any method in the table.
  • On a Benefit with cards, claims-based funding on its own is rejected with BAD_REQUEST. Use RMF, or RMF and claims-based.

The Partner API does not show whether a Benefit has cards, and it cannot change this setting. A new Benefit gets the setting from its template. To find out whether your templates have cards, or to change the setting, contact [email protected].

Read the funding method​

Select fundingConfiguration on a Benefit.

query BenefitFundingMethod($id: ID!) {
benefit(where: { id: $id }) {
... on Benefit {
id
fundingConfiguration {
balanceFundingAlgorithm
strategy
rmf {
enabled
schedule {
frequency
days
}
thresholdPercentage
thresholdAmount {
currency
lowestDenominationAmount
}
}
claimFunding {
enabled
schedule {
frequency
days
}
}
}
}
... on BadRequestError {
code
message
}
}
}

This Benefit uses claims-based funding with a daily schedule, and it has no RMF settings:

{
"data": {
"benefit": {
"id": "<benefitId>",
"fundingConfiguration": {
"balanceFundingAlgorithm": "NONE",
"strategy": "EMPLOYER_FUNDED",
"rmf": null,
"claimFunding": {
"enabled": true,
"schedule": {
"frequency": "DAILY",
"days": []
}
}
}
}
}
}

The fields of BenefitFundingMethod:

  • balanceFundingAlgorithm is RMF, NONE, FULL_COMMITMENT or CONTRIBUTION_BASED.
  • rmf holds the stored RMF settings. It is null when the Benefit stores none. The settings stay stored when the algorithm is not RMF, and they have no effect until it is.
    • enabled: when false, RMF calculates the funding but creates no funding events.
    • schedule: when RMF runs. See Schedules.
    • thresholdPercentage: the minimum balance as a fraction, from 0.0 to 1.0, of the total commitment.
    • thresholdAmount: the minimum balance as an amount of money.
  • claimFunding holds the stored claims funding settings. It is null when the Benefit stores none.
    • enabled: whether claims funding is on.
    • schedule: when claims funding runs. If enabled is true and schedule is null, it runs daily.
  • strategy is EMPLOYER_FUNDED or PARTNER_FUNDED. It shows who funds the Benefit. You cannot change it through the Partner API.

A Benefit with no stored funding settings reads as NONE, with rmf and claimFunding both null.

note

fundingConfiguration is not the same as configuration.funding. Benefit.configuration.funding holds the funding limits and the initial funding amounts of the Benefit. It does not hold the funding method.

Change the funding method​

Call updateBenefitFundingMethod with the benefitId and at least one of balanceFundingAlgorithm, rmf or claimFunding. A value that you omit stays as it is.

mutation UpdateBenefitFundingMethod($input: UpdateBenefitFundingMethodInput!) {
updateBenefitFundingMethod(input: $input) {
... on UpdateBenefitFundingMethodResult {
benefitId
fundingConfiguration {
balanceFundingAlgorithm
rmf {
enabled
schedule {
frequency
days
}
thresholdPercentage
thresholdAmount {
currency
lowestDenominationAmount
}
}
claimFunding {
enabled
schedule {
frequency
days
}
}
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}

The result returns the funding method of the Benefit after the change. The examples that follow use this mutation with different variables.

Switch to claims-based funding​

This funds approved claims each Monday. The Benefit must not have cards. See Benefits with cards.

{
"input": {
"benefitId": "<benefitId>",
"balanceFundingAlgorithm": "NONE",
"claimFunding": {
"enabled": true,
"schedule": { "frequency": "WEEKLY", "days": [1] }
}
}
}

Switch to RMF​

This keeps the balance at or above 20% of the total commitment, and runs each Monday.

{
"input": {
"benefitId": "<benefitId>",
"balanceFundingAlgorithm": "RMF",
"rmf": {
"enabled": true,
"schedule": { "frequency": "WEEKLY", "days": [1] },
"threshold": { "percentage": 0.2 }
}
}
}

If claims funding is already on for the Benefit, it stays on, and the Benefit then uses both methods.

Change the RMF threshold​

This changes the threshold to $500.00 and leaves the algorithm and the claims funding settings as they are. The threshold replaces the stored one, so a change from a percentage to an amount needs only the new field.

{
"input": {
"benefitId": "<benefitId>",
"rmf": {
"enabled": true,
"schedule": { "frequency": "WEEKLY", "days": [1] },
"threshold": {
"amount": { "currency": "USD", "lowestDenominationAmount": 50000 }
}
}
}
}

Turn claims funding off​

{
"input": {
"benefitId": "<benefitId>",
"claimFunding": {
"enabled": false,
"schedule": { "frequency": "WEEKLY", "days": [1] }
}
}
}

Rules​

  • Send rmf only when the algorithm after the change is RMF.
  • Send rmf.enabled and rmf.schedule with every rmf input. Send claimFunding.schedule with every claimFunding input, also when you change only enabled. The values that you send replace the stored values.
  • Send rmf.threshold with exactly one of percentage (0.0 to 1.0) or amount (in USD). Omit rmf.threshold to keep the stored threshold.
  • A switch away from RMF keeps the stored RMF settings. A later switch back to RMF uses them.
  • You cannot remove stored rmf or claimFunding settings. To stop RMF, set the algorithm to NONE. To stop claims funding, set claimFunding.enabled to false.
  • An RMF Benefit can show rmf as null, or both thresholds as null. It then funds to a default of 10%. If your change leaves such a Benefit on RMF, send a threshold with the change. Otherwise the change is rejected with BAD_REQUEST.
  • The mutation has no idempotency key. If you send the same input again, the stored settings stay the same.

Schedules​

A schedule has a frequency and a list of days.

frequencydays
DAILYOmit days. A read returns an empty list.
WEEKLY0 to 6. Sunday is 0. Send at least one day.
MONTHLY1 to 31. Use 31 for the last day of each month. Send at least one day.

When a change takes effect​

  • You can change the funding method while the Benefit is active. The change applies to new funding runs.
  • Funding events that exist at the time of the change are not changed.
  • If you turn claims funding off, approved claims that wait for the claims funding run of that Benefit are not funded by that run.
  • A change to the funding of an employer-funded Benefit can send a notification to the administrators of the Organization.

Divisions​

Each Division of an Organization has its own funding method. The funding method does not pass from the Benefit of the parent Organization to its Divisions.

  • A change applies only to the Benefit that you name.
  • A Division that exists at the time of a change to the parent Benefit keeps its own funding method.
  • A Division that is created after a change to the parent Benefit gets the funding method of the parent.
  • When the claims funding run selects the parent Benefit, it also funds the claims that wait for funding in the Divisions. A Division with claims funding off can therefore still get funding through the parent.

benefit and updateBenefitFundingMethod accept the ID of a Division's Benefit. benefitsPrograms returns only the Benefits of the parent Organization. To get the ID of a Division's Benefit, contact [email protected].

Other operations, such as enrollment and funding an Individual, use the Benefit of the parent Organization. See Offerings & Enrollment Across Divisions.

Template defaults​

Select fundingConfiguration on a BenefitTemplate to read the funding defaults that the template stores for you.

query BenefitTemplateFundingDefaults {
benefitTemplates {
... on BenefitTemplatesResults {
nodes {
id
name
type
fundingConfiguration {
balanceFundingAlgorithm
strategy
rmf {
enabled
thresholdPercentage
}
claimFunding {
enabled
}
}
}
}
}
}
  • A null field means that the template sets no value for it. It does not mean that funding is off.
  • A new Benefit also takes funding defaults from your account and from the Organization. For this reason, the template alone does not tell you the funding method that a new Benefit gets. Read the Benefit after you create it.
  • A change to a template default does not change existing Benefits.
  • You cannot change template defaults through the Partner API.

Bank account​

For an employer-funded Benefit, RMF and claims-based funding pull from the employer bank account that is linked to the Benefit. If no bank account is linked, no funding pull occurs.

The Partner API cannot link a bank account to a Benefit. Link it in Health Wallet Manager before you rely on automated funding.

Errors​

updateBenefitFundingMethod returns BadRequestError with one of these codes:

codeMeaning
NOT_FOUNDNo Benefit of yours has this benefitId.
BAD_REQUESTThe input is not valid. See the list after this table.
FUNDING_NOT_EDITABLEThe Benefit is cancelled, or its funding cannot be edited.
FUNDING_FIELD_NOT_WRITABLEYou cannot make this change on this Benefit.
FUNDING_ALGORITHM_LOCKEDThe balance funding algorithm of this Benefit cannot be changed. This applies to an HSA Benefit.
FUNDING_GUARDRAIL_VIOLATIONA threshold is outside the allowed range for the schedule. The message gives the range.
EMERGENCY_THRESHOLD_CONFLICTA stored emergency funding setting prevents this threshold change. Contact developer support.
IMMEDIATE_SETTLEMENT_CONFLICTAutomated funding conflicts with the immediate settlement of contributions on this Benefit.
PUSH_FUNDING_CONFLICTThe change conflicts with the push funding of this Benefit.

For BAD_REQUEST, the message tells you what to correct. Some mistakes get a message that names the fields:

  • An input with none of balanceFundingAlgorithm, rmf or claimFunding.
  • rmf sent when the algorithm after the change is not RMF.
  • A threshold that is missing, has both fields, or has an amount that is not in USD.

Other mistakes all get the same message:

  • Schedule days that are missing or out of range.
  • A threshold value that is out of range.
  • Claims-based funding on its own on a Benefit with cards.
The funding configuration is not valid for Benefit=<benefitId>. Check the schedule days, the threshold values, and that claims funding is compatible with cards on this Benefit.

If the call returns InternalServerError with a message that says the change was saved, do not send the change again. Read the Benefit to see its funding method.