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.
| Operation | Use it to |
|---|---|
| benefit | Read the funding method of a Benefit, in its fundingConfiguration field. |
| benefitTemplates | Read the funding defaults that a template gives to new Benefits. |
| updateBenefitFundingMethod | Change 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
| Method | Settings | What it does |
|---|---|---|
| RMF | balanceFundingAlgorithm: RMF, with rmf | Keeps the balance of the Benefit's account above a threshold, on the RMF schedule. |
| Claims-based | balanceFundingAlgorithm: NONE, with claimFunding.enabled: true | Funds each approved claim, on the claims funding schedule. |
| RMF and claims-based | balanceFundingAlgorithm: RMF, with claimFunding.enabled: true | Does both. |
| None | balanceFundingAlgorithm: NONE, with claims funding off or absent | First 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:
balanceFundingAlgorithmisRMF,NONE,FULL_COMMITMENTorCONTRIBUTION_BASED.rmfholds the stored RMF settings. It isnullwhen the Benefit stores none. The settings stay stored when the algorithm is notRMF, and they have no effect until it is.enabled: whenfalse, 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.
claimFundingholds the stored claims funding settings. It isnullwhen the Benefit stores none.enabled: whether claims funding is on.schedule: when claims funding runs. Ifenabledistrueandscheduleisnull, it runs daily.
strategyisEMPLOYER_FUNDEDorPARTNER_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.
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
rmfonly when the algorithm after the change isRMF. - Send
rmf.enabledandrmf.schedulewith everyrmfinput. SendclaimFunding.schedulewith everyclaimFundinginput, also when you change onlyenabled. The values that you send replace the stored values. - Send
rmf.thresholdwith exactly one ofpercentage(0.0 to 1.0) oramount(inUSD). Omitrmf.thresholdto keep the stored threshold. - A switch away from
RMFkeeps the stored RMF settings. A later switch back toRMFuses them. - You cannot remove stored
rmforclaimFundingsettings. To stop RMF, set the algorithm toNONE. To stop claims funding, setclaimFunding.enabledtofalse. - An RMF Benefit can show
rmfasnull, or both thresholds asnull. 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 withBAD_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.
frequency | days |
|---|---|
DAILY | Omit days. A read returns an empty list. |
WEEKLY | 0 to 6. Sunday is 0. Send at least one day. |
MONTHLY | 1 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
nullfield 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:
code | Meaning |
|---|---|
NOT_FOUND | No Benefit of yours has this benefitId. |
BAD_REQUEST | The input is not valid. See the list after this table. |
FUNDING_NOT_EDITABLE | The Benefit is cancelled, or its funding cannot be edited. |
FUNDING_FIELD_NOT_WRITABLE | You cannot make this change on this Benefit. |
FUNDING_ALGORITHM_LOCKED | The balance funding algorithm of this Benefit cannot be changed. This applies to an HSA Benefit. |
FUNDING_GUARDRAIL_VIOLATION | A threshold is outside the allowed range for the schedule. The message gives the range. |
EMERGENCY_THRESHOLD_CONFLICT | A stored emergency funding setting prevents this threshold change. Contact developer support. |
IMMEDIATE_SETTLEMENT_CONFLICT | Automated funding conflicts with the immediate settlement of contributions on this Benefit. |
PUSH_FUNDING_CONFLICT | The 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,rmforclaimFunding. rmfsent when the algorithm after the change is notRMF.- 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.