Overview
When a coordinator assigns a caregiver to a shift through Caribou, a pay code determines the caregiver's rate of pay.
Most of the time, coordinators do not need to think about pay codes. The system selects the right one automatically based on the caregiver's profile, the visit’s discipline requirements, and organization level configuration.
This guide explains how the system works, when coordinator input is needed, and how to set up defaults.
Quick Reference
| Question | Answer |
|---|---|
| Do coordinators need to pick a pay code every time? | No. Most of the time it is selected automatically. Manual selection is only needed when no automatic match is found. |
| What determines the pay code? | Caregiver's office + disciplines, visit discipline, org default configuration |
| Can I assign visits with different disciplines at once? | No. This is a new restriction. Select one discipline at a time. |
| When are default pay codes needed? | Only when HHAeXchange does not return a pay code for the visit. |
| What do I need from the agency? | Just the pay code name per discipline. Caribou handles the rest. |
How It All Connects: Service Codes, Disciplines, and Pay Codes
These three concepts form a chain. Understanding this chain helps when troubleshooting pay code issues.
| Concept | What It Is | Example |
|---|---|---|
| Service Code | A code on the visit in HHAeXchange that describes the type of care being delivered | "PCA Hourly" or "HHA Live-In" |
| Discipline | The certification level required. Every service code has a discipline. Every caregiver has one or more disciplines they are allowed to work. | HHA, PCA, HMK, HSK |
| Pay Code | The rate of pay for the caregiver. Defined at the office level in HHAeXchange. Pay codes can sometimes be assigned to multiple offices. Each pay code has a discipline attached to it. | "HHA_Hourly Pay Code" (discipline: HHA, ID: 145030) |
The chain:
- A visit has a service code (set by the agency in HHAeXchange)
- The service code determines the visit's discipline (e.g., PCA)
- When a caregiver is assigned, a pay code must be selected
- The pay code's discipline must match one of the caregiver's allowed disciplines
💡Key point: The pay code's discipline must match the caregiver's qualifications, not necessarily the visit's discipline. An HHA-qualified caregiver working a PCA visit could use either an HHA or PCA pay code.
How Pay Code Selection Works
The system goes through several steps to find the right pay code. In most cases, it finds one automatically and the coordinator does not need to do anything.
What pay codes are available?
The system currently retrieves pay codes based on:
- Office match: The pay code must be available for the caregiver's assigned office(s)
- Discipline match: The pay code must match one of the caregiver's discipline(s)
For example, if a caregiver has:
- Office: Branch A
- Disciplines: HHA, PCA
They will only see pay codes that:
- Are configured for Branch A, AND
- Are designated for HHA or PCA disciplines
💡 Please reach out to your CSM if your agency pay code distribution works differently.
How the system picks a default pay code
When assigning a visit, the system attempts to complete the assignment without explicitly setting a pay code. If the assignment fails due to missing pay code, our system tries to select the best pay code automatically. Here is the priority:
Step 1: Check organization default pay code configuration
Your organization can configure default pay codes for each discipline (HHA, PCA, RN, LPN, etc.) in Caribou's shift booking settings. Multiple defaults can be configured per discipline to cover different offices.
Step 2: Match the visit's discipline
The system looks at the discipline of the visit(s) being assigned. If the visit has no discipline information, no default will be selected.
Step 3: Find matching pay codes
The system finds pay codes that are both:
- Available to the caregiver (correct office + discipline)
- Listed in the organization's configured defaults for the visit's discipline
Step 4: Select the best match
| Scenario | What Happens |
|---|---|
| Exactly one match | That pay code is automatically pre-selected |
| Multiple matches, different disciplines | The system picks the highest-ranking discipline: HHA > PCA > HMK > HSK. For disciplines outside this hierarchy (RN, LPN, etc.), the first match is selected. |
| Multiple matches, same discipline | One of the matching pay code is selected |
| No matches | No default is pre-selected. The coordinator must choose manually from the dropdown. |
What the Coordinator Sees
In the most common case, the coordinator just clicks Assign and the pay code is handled automatically. Here is the full range of what can happen:
| Situation | Coordinator Experience | How Common |
|---|---|---|
| A pay code is pre-selected in HHA for that visit | Clicks assign and task completed | Most common |
| System finds match via defaults | Default pay code is pre-selected. Coordinator reviews and confirms. | Common (fallback) |
| No match found | Dropdown is empty. Coordinator must pick a pay code manually. | Uncommon |
The confirmation modal shows:
- The visit discipline for each selected shift
- A pay code dropdown — each option shows the discipline in parentheses (e.g., "HHA_Hourly Pay Code (HHA)")
⚠️ Pay code is a mandatory field for successful assignment through Caribou.
What Changed: Multi-Discipline Assignment
⚠️ This is a change from previous behavior. Previously, coordinators could select multiple visits with different disciplines and assign them all at once. This is no longer allowed.
Why: Different disciplines usually require different pay codes. Mixing them risked applying the wrong pay code.
In practice: If a caregiver has 2 PCA shifts and 2 HHA shifts, the coordinator assigns them in two steps:
- Select the 2 PCA shifts → Assign
- Go back, select the 2 HHA shifts → Assign
If the coordinator selects mixed disciplines:
- An error message appears
- The Assign button is disabled
- They deselect visits until only one discipline remains
Default Pay Code Configuration
Default pay codes are configured by the Caribou team. They map a visit discipline to a specific pay code so it can be pre-selected automatically.
Each mapping includes:
| Field | Description |
|---|---|
| Discipline | The visit discipline this default applies to (e.g., HHA, PCA) |
| Pay Code Name | Human-readable name (e.g., "HHA_Hourly Pay Code") |
✅ When are defaults needed? Defaults are needed when there are multiple pay code options, but usually you want a coordinator to select the same pay code every time. Defaults will remove the need for coordinators to have to choose that same pay code every time.
Discipline Hierarchy
Caribou uses a discipline hierarchy for two purposes: (1) determining which caregivers can see which shifts, and (2) picking between multiple matching default pay codes.
| Tier | Discipline | Can Work |
|---|---|---|
| 1 (highest) | HHA (Home Health Aide) | HHA, PCA, HMK, HSK shifts |
| 2 | PCA (Personal Care Aide) | PCA, HMK, HSK shifts |
| 3 | HMK (Homemaker) | HMK, HSK shifts |
| 4 (lowest) | HSK (Housekeeper) | HSK shifts only |
For disciplines outside this hierarchy (RN, LPN, etc.), the system uses the first available match.
Limiting which disciplines see shifts
Some agencies only want certain disciplines in shift booking. This is controlled through caregiver segmentation. Your Caribou CSM can configure which disciplines have access to the Shifts tab.
Providing Default Pay Codes to Your Caribou CSM
💡 This section is for agency administrators or managers setting up shift booking with Caribou.
What your CSM needs from you
For each discipline your agency uses in shift booking, your CSM needs one piece of information:
"When a coordinator assigns a caregiver to a [discipline] shift and needs to pick a pay code, which one do they normally use?"
Just the pay code name is enough. The Caribou team looks up the ID and office mappings.
When you might not need to provide this
If HHAeXchange assign works without requiring a specific pay code, the system will be able to assign shifts automatically.
If you don’t have default pay codes, and your coordinators knows which pay codes to use for shifts, then they could select the desired pay code when assigning. Your CSM can help you confirm.
What to send your CSM
For each type of shift, provide the pay code your coordinators normally select:
- For HHA shifts: which pay code? (e.g., "HHA_Hourly")
- For PCA shifts: which pay code? (e.g., "PCA_Hourly")
Just the name is fine — the Caribou team handles the technical setup.
Example submission
| Discipline | Default Pay Code Name |
|---|---|
| HHA | HHA_Hourly Pay Code |
| PCA | PCA_Hourly Pay Code |
✅ Tip: Check with your champion or a manager. Coordinators may not be very familiar with the pay codes.
Troubleshooting
No pay code is pre-selected when assigning
This means neither HHAeXchange nor the default configuration returned a match. It could be that: (1) no default is configured for this discipline, or (2) the caregiver's office does not match the configured defaults. Collect the pay code name from the agency and submit to the Caribou team.
Wrong pay code is pre-selected
The default mapping may not match the agency's workflow. Ask the coordinator which pay code they normally use and submit an update. If the issue is the visit discipline in HHAeXchange, the agency needs to fix it there.
Error when selecting multiple visits
The selected visits have different disciplines. This is a new restriction — go back and select only visits with the same discipline.
Can I assign without a pay code?
No, this is mandatory.
- Coordinator does not know which pay code to use
If the coordinator is unsure, they should confirm with the payroll department before assigning the shift. Payroll owns pay code accuracy and compliance.
If payroll indicates that different pay codes are used situationally (e.g., depending on HHA vs PCA, client type, overtime status, etc.), this should be flagged to the product team for clearer system guidance or rule automation.
Caregiver cannot see shifts in the app
The caregiver's discipline may be excluded via caregiver segmentation, or they may not be integrated with HHAeXchange. Check with your Caribou CSM.
Need Help?
- Contact your Caribou Customer Success Manager to set up or change default pay codes.
- For pay code changes in HHAeXchange, update there first, then notify your Caribou CSM.
- For discipline hierarchy or segmentation questions, contact your CSM.
- For patterns of overrides or data mismatches, flag to the CSM.