How to import benefit costs (Bring Your Own Benefits) — Employer guide
Bring Your Own Benefits (BYOB) lets you upload your Global Payroll employees' benefit costs into Remote in bulk from a spreadsheet, so they're reflected on the Cost management page. Who it's for: Global Payroll employees whose benefits you administer yourself. It is not used for benefits managed through a Remote-integrated benefits provider — those costs sync automatically.
- This import is only for Global Payroll employees. Costs uploaded against non‑Global‑Payroll employments will be rejected as “Employment is not eligible.”
- Have your benefit cost data ready in a spreadsheet (CSV). You can use your own column layout — Remote will map it for you (see How automatic mapping works).
- Know the currency of each cost and the month it applies to.
- You are responsible for the accuracy of the data you upload. Avoid uploading costs that are already coming into Remote from an integrated benefits provider, to prevent duplicates.
The upload is a short, guided flow with four steps:
- Upload data — upload your CSV file.
- Map fields — Remote auto-maps your columns to the expected fields; you confirm or adjust anything it couldn't match.
- Review data — Remote validates every row and flags anything that needs attention. You fix issues inline (or re-upload a corrected file).
- Confirm — submit. The costs are created and appear on your Cost management page.
You don't need a fixed template: you can upload a spreadsheet in whatever shape your current system exports, and map the columns in step 2. The fields below describe what information each row needs to contain.
Each row = one benefit cost for one employee, for one month. An employee can appear on multiple rows (e.g. an employer-paid premium, an employee-paid premium, and a tax line).
The fields fall into four groups: Employee, Benefit plan, Coverage, and Cost.
1. Employee — who the cost is for
Provide at least one way to identify the employee. Email is the simplest; the employment ID (slug) is the most precise.
Field | Required? | Notes |
|---|---|---|
| Recommended | The employee's email in Remote. Reliable, unique matcher. |
| Optional | The employment ID. The most precise match if you have it. |
| Optional | Full name. Used to match if no email/slug is given. |
| Optional | Alternative to |
You must include enough to uniquely identify the employee — at minimum an email, an employment ID, or a full name that matches a Global Payroll employee in your company.
2. Benefit plan — what the benefit is
Field | Required? | Notes |
|---|---|---|
| Required | The provider/insurer name, e.g. VisionPlus. |
| Required | The plan name, e.g. Employee Vision Plan. |
| Required | The kind of benefit — must be one of the accepted values (see Accepted values). |
3. Coverage — the coverage period
Field | Required? | Notes |
|---|---|---|
| Required | When coverage starts. Format |
| Optional | When coverage ends. Leave blank if ongoing. |
| Optional | Number of dependents covered (whole number). |
4. Cost — the amount and what it represents
Field | Required? | Notes |
|---|---|---|
| Required | The cost amount, e.g. |
| Required | 3-letter ISO currency code, e.g. |
| Required | What the cost represents — one of the accepted values (see below). |
| Required | The payroll month the cost applies to. Use the first of the month, e.g. |
| Required | Who pays the cost: |
| Optional | Free-text note for context. |
Benefit plan type (external_benefit_plan.type) — use one of:
allowance, childcare, critical-illness, dental, employee-assistance-program, funeral-coverage, health, hospital-coverage, income-protection, meal, personal-accident, travel, transportation, vision, workers-compensation, workplace-accident, mental-wellbeing, health-savings-account, flexible-spending-account, perks, ad&d, life-plus-ad&d, life, disability, pension.
(health-and-dental still exists for older plans but is deprecated — don't use it for new imports.)
Cost category (benefit_cost.category):
Value | Meaning |
|---|---|
| The recurring premium for the benefit. |
| A tax associated with the benefit. |
| A tax relief/reduction associated with the benefit. |
| A service/administration fee. |
| A voluntary deduction from the employee. |
| Pro-rated amounts for partial first/last months of coverage. |
| US-specific categories. |
*correction is also a valid category in the platform, but it's used by the separate Correct costs flow — not for creating new costs here. tax_relief is accepted but rarely used.*
Payor (benefit_cost.payor): employer or employee.
Values must match exactly (lower-case, as written). For example, use health — not “Health Insurance”. If a value isn't recognized, Remote flags the cell in the Review step and lets you pick the correct value from a dropdown.
A sample CSV for one employee with an employer-paid premium, an employee-paid premium, and an employee tax line, all for June 2026:
employee.email,external_benefit_plan.carrier_name,external_benefit_plan.name,external_benefit_plan.type,external_benefit.coverage_start_date,external_benefit.coverage_end_date,external_benefit.dependents_count,benefit_cost.amount,benefit_cost.currency,benefit_cost.category,benefit_cost.effective_month,benefit_cost.payor
jane.doe@acme.com,VisionPlus,Employee Vision Plan,vision,2026-06-01,,1,150.00,USD,premium,2026-06-01,employer
jane.doe@acme.com,VisionPlus,Employee Vision Plan,vision,2026-06-01,,1,30.00,USD,premium,2026-06-01,employee
jane.doe@acme.com,VisionPlus,Employee Vision Plan,vision,2026-06-01,,1,10.00,USD,tax,2026-06-01,employee
Step 1 — Open Cost management
In the left menu, go to Benefits → Cost management (/dashboard/benefits/costs). On the Cost management page, click Bulk actions and choose Create costs
Step 2 — Upload data
The upload opens on the Add benefit costs screen (badged For external benefits only). Upload your CSV file (drag-and-drop or browse), then continue.
Step 3 — Map fields
Remote auto-maps your file (you'll briefly see Auto-mapping CSV to Remote data…). The step prompt reads: Select the column title in your file that matches the corresponding field title in Remote's platform. Review the mapping, use the dropdowns to map any column it couldn't match, then select Confirm and continue. See How automatic mapping works.
Step 4 — Review data
On the Review benefit costs step, Remote validates every row: If there are errors, you can select rows or cells to make changes. You can also export rows to a new file, make changes there, and then upload that file. A banner shows the count, e.g. 3 costs can't be added due to errors. To fix issues you can:
- Turn on Show only rows with errors and edit values inline (e.g. pick a valid category from a dropdown).
- Turn on Show only required and conditional columns to focus on what matters.
- Use Actions and Filter on the table, or export the errored rows, fix them in your file, and re-upload.
- Save as draft to finish later.
When all rows are clear, select Continue with [N] costs (this reads Resubmit [N] costs after a re-upload).
Step 5 — Confirm
Review the summary and confirm. Your benefit costs are created and appear on the Cost management page.
You don't have to format your file to an exact template. When you upload, Remote does the matching for you in three ways:
- Column mapping. Remote reads your column headers and auto-maps them to the expected fields (with smart, AI-assisted suggestions). Any column it can't confidently match is left for you to map with a dropdown in the Map fields step.
- Employee matching. For each row, Remote matches the employee in this order: by employment ID (slug) if present → otherwise by email → otherwise by name. If it still can't find a unique match, you'll be asked to choose the employee.
- Value matching. For fields with a fixed set of values (benefit plan type, cost category, payor), Remote checks your values against the accepted list. Anything that doesn't match (e.g. “Health Insurance” instead of
health) is flagged in Review, where you select the correct value from a dropdown.
Message | What it means | How to fix |
|---|---|---|
Employment is not eligible | The employee isn't a Global Payroll employee. This import only supports Global Payroll employments. | Remove non‑Global‑Payroll rows, or upload for a Global Payroll employee. |
Employee not found | The email / employment ID / name didn't match anyone in your company. | Check the value and that the employee exists under your company; prefer email or employment ID. |
Invalid type / category / payor | The value isn't one of the accepted values. | Pick the correct value from the dropdown in Review, or fix it in your file and re-upload. |
Missing required field | A required column is empty (carrier name, plan name, type, coverage start date, amount, currency, category, effective month, or payor). | Fill in the missing value. |
Invalid date | A date isn't in the expected format. | Use |
Do I have to use a specific template?
No. Upload your own CSV layout — Remote maps your columns for you. Including the fields above (especially an employee identifier and the required fields) makes mapping smooth.
Which employees can I upload costs for?
Global Payroll employees whose benefits you administer.
What date format should I use?
YYYY-MM-DD. For effective_month, use the first day of the month the cost applies to.
Can I save my progress and finish later?
Yes — use Save as draft during the Review step.
What happens if some rows have errors?
Valid rows can still be submitted; rows with errors are held back until you fix them. You can edit inline or export, correct, and re-upload.
How do I avoid duplicate costs?
Don't upload costs that are already flowing into Remote from an integrated benefits provider. You're responsible for the data you import.
