Product Codes

A product code is the key an external platform uses to identify an account type in its own systems. First Dollar records one product code per Benefit template per platform, so every Benefit created from that template carries the same code. Product codes are set by First Dollar during implementation; they are not writable through the Partner API.

Product codes are distinct from the external IDs described in External IDs. An external ID identifies a specific Organization, Division, or Individual; a product code classifies a Benefit's type.

Finding your platform ID

Product codes are read and filtered per external platform. Each platform linked to your account has an ID that is specific to your account and stable for its lifetime. Query linkedExternalPlatforms once and keep the id; it is the only place the ID is published. The query returns IDs only, so if more than one platform is linked to your account, First Dollar tells you which ID belongs to which platform during implementation.

query LinkedPlatforms {
  linkedExternalPlatforms {
    ... on LinkedExternalPlatformsResults {
      platforms {
        id
      }
    }
  }
}

Pass the id as platformIds on individuals, as platformId in Individual.healthWallet(where:), and as platformId on Benefit.productCode. If exactly one platform is linked to your account, platformId may be omitted on productCode, and on healthWallet when filtering by productCodes, and that platform is used. With no linked platform, or more than one, omitting it there is rejected with extension code BAD_USER_INPUT. A healthWallet call that does not filter by productCodes never needs a platform. The examples below always pass the ID.

Reading a product code

Benefit.productCode(platformId) returns the code recorded for that platform, or null when none is recorded. Benefit.type is still the First Dollar BenefitType.

query BenefitProductCodes($where: IndividualsFilterInput!, $platformId: ID!) {
  individuals(where: $where) {
    ... on IndividualsResults {
      nodes {
        id
        healthWallet {
          accounts {
            id
            availableBalance {
              amount
              display
            }
            currentBalance {
              amount
              display
            }
            electionAmount {
              amount
              display
            }
            benefit {
              id
              name
              type
              productCode(platformId: $platformId)
            }
          }
        }
      }
    }
  }
}

Filtering a Health Wallet by product code

HealthWalletFilterInput accepts platformId and productCodes together. Only accounts whose Benefit carries one of the codes on that platform are returned. Values are matched exactly, an explicitly empty list matches no accounts, and platformId without productCodes is rejected with extension code BAD_USER_INPUT. The filter composes with statuses.

query HsaBalanceForPlatformMember($platformId: ID!) {
  individuals(where: { externalUserIds: ["<platform-member-id>"], platformIds: [$platformId] }) {
    ... on IndividualsResults {
      nodes {
        id
        healthWallet(where: { platformId: $platformId, productCodes: ["HSA"] }) {
          accounts {
            id
            availableBalance {
              amount
            }
            currentBalance {
              amount
            }
            benefit {
              productCode(platformId: $platformId)
            }
          }
        }
      }
    }
  }
}

The individuals lookup above uses externalUserIds with platformIds to find the member by the identifier recorded for that platform. Read the result as follows:

• Empty nodes: no Individual holds that identifier on the platform, or the only match has no name on file (Individuals without a resolvable name are never returned by individuals).
• A node whose healthWallet.accounts is empty: the member exists but has no account with one of the requested product codes.
• More than one node: an identifier is not unique on a platform, so one value can match several Individuals. Compose organizationIds or ids to narrow the result. Terminated members are returned unless you also compose statuses.

See IndividualsFilterInput for the matching rules.

Which balance to read

Both balances are available on every account; read the one that matches the figure you display. The Partner API floors both availableBalance and currentBalance at zero on every account type, so neither is reported below zero even when the underlying ledger is. Separately, a reversal cannot take an HSA's available balance below zero; see the HSA funding guide.

• availableBalance is the amount the member can spend now.
• currentBalance is the ledger balance. The two differ while money movement is in flight, such as a pending contribution or an authorized card transaction that has not settled.

electionAmount is the annual election, or null when none is set. It applies to HSA and FSA accounts only.

The product codes recorded for your platform are agreed with First Dollar during implementation; contact [email protected] for the list.