CSV Imports for BillingOne
BillingOne accepts CSV uploads in two places: the Billing catalog (products and services) and Gorelo contract import (bulk draft service contracts). This guide documents both formats.
Catalog CSV
Where: BillingOne → Catalog → Import CSV
Catalog CSV rows create PanelOne catalog items with source: csv. They are useful for SKUs you sell in BillingOne before mirroring them in Xero or QuickBooks.
Detecting headers vs. positional rows
The importer inspects the first line:
- If the first line contains
code,name, oritem(case-insensitive), it is treated as a header row and skipped. - Otherwise, every line is parsed as headerless positional data (see below).
Column reference (with headers)
| Column | Required | Aliases | Notes |
|---|---|---|---|
code | No | sku, item code | Uppercased on import |
name | No* | item, product | Display name |
description | No | desc | Longer text |
default_unit_price | No | unit_price, price | Commas stripped; blank → null |
default_unit_cost | No | unit_cost, cost | Commas stripped; blank → null |
| Tax column | No | xero_tax_type, qbo_tax_code, tax | Uses connected provider's tax column |
*If both code and name are blank, the row name falls back to CSV item.
Headerless positional format
When the first line is not a header, columns are read by position:
| Position | Field |
|---|---|
| 1 | code |
| 2 | name |
| 3 | description |
| 4 | default_unit_price |
| 5 | default_unit_cost |
| 6 | Tax code (xero_tax_type or qbo_tax_code depending on provider) |
Example (headerless):
MWS-001,Managed Workstation,Per-device managed support,75.00,,
PLAT-FEE,Platform Fee,Monthly platform charge,500.00,,
Blank code behavior
If code is empty after parsing, BillingOne assigns an auto-generated code:
CSV-{8-char-uuid}
Example: CSV-A1B2C3D4. The code is uppercased. Assign a proper SKU by editing the row after import, or include a code column in your CSV.
After import
CSV rows do not automatically get revenue account (GL) mappings. Open each new row (or bulk-edit in the catalog editor) and set:
- Default revenue account — required before Xero/QBO push if the line has no account from sync
- Tax code — if not supplied in the CSV
Gorelo Contract CSV
Where:
- BillingOne dashboard → Gorelo billing migration → Import from Gorelo CSV
- Settings → Integrations → Invoice Settings (same import card when Gorelo is connected)
Requires permission billing.contracts.manage.
Gorelo's public API does not expose billing contracts — this CSV path is for exports you build from Gorelo agreement reports or manual transcription.
Column reference
| Column | Required | Default | Aliases |
|---|---|---|---|
client_name | Yes | — | client, company, company_name, client name, company name |
line_description | Yes | — | description, line description, service, item, service description |
line_type | No | fixed_recurring | type, line type |
quantity | No | 1 | qty, count |
unit_price | No | 0 | price, unit price, rate, amount |
billing_cadence | No | monthly | cadence, billing cadence, frequency, billing frequency |
Header matching is flexible — aliases are normalized (lowercase, punctuation → underscores).
Valid line_type values
If omitted or unrecognized, defaults to fixed_recurring:
fixed_recurringmeteredpax8_linkedtime_materialsmanuallabour_unlimitedlabour_blocklabour_per_hour
Valid billing_cadence values and aliases
| Value | Accepted aliases |
|---|---|
monthly | month |
quarterly | quarter, qtr |
semiannual | biannual, 6month |
annual | annually, yearly, year |
custom | — |
Unrecognized cadence values default to monthly.
Currency and number parsing
$and,are stripped fromunit_priceandquantity- Empty
quantity→1; emptyunit_price→0
Example
client_name,line_description,line_type,quantity,unit_price,billing_cadence
Acme Corp,Managed Workstation Support,fixed_recurring,25,75,monthly
Acme Corp,Server Monitoring,fixed_recurring,3,120,monthly
Beta LLC,Monthly Platform Fee,fixed_recurring,1,500,monthly
Download the in-app sample template (gorelo-contract-import-template.csv) from the import wizard for a ready-to-edit file.
Import wizard flow
- Upload CSV — paste or upload; fix parse errors shown per row
- Preview & match clients — rows grouped by
client_name; PanelOne clients matched by exact then fuzzy name; override unmatched rows manually - Create drafts — one draft service contract per matched client; open each draft to attach catalog items, review cadence, and publish
Gorelo import limitations
- Creates draft contracts only — does not publish or generate invoices
- Does not map Xero/QBO catalog items — attach catalog items in the contract editor after import
- One cadence per contract — if a client has mixed cadences in the CSV, the wizard uses the most common value for the contract header
- Client name matching only — map Gorelo companies to PanelOne clients first (Settings → Integrations → Client Mappings) for best results
Parity Backlog
| Feature | Status |
|---|---|
| Late fees | Implemented — manual Apply late fee on overdue invoices; optional Auto-apply late fees (daily cron); fee line added to invoice totals; Xero sync set to drift when re-push needed |
| Statements | Implemented — /statements with print HTML, Download PDF (jspdf), and Email statement via SMTP2GO |
| Branded PDF | Implemented — native Download PDF on invoices and statements (jspdf); org logo/accent from branding settings |
| Payment term presets | Implemented — Net 7/14/30/45/60 presets in invoice settings and client edit dialog |
| Credit note tax picker | Implemented — per-line tax and GL account on credit note editor |
| Quote / template tax | Implemented — per-line tax override on quotes and contract templates |
| Chart of accounts admin | Implemented — editable COA at /chart-of-accounts; manual accounts + edit synced rows |
| Mobile tax editing | Implemented — tax picker modal on draft contract/invoice lines in billingone-mobile |
Still not built / partial
| Feature | Notes |
|---|---|
| Auto late-fee Xero push | Late fee updates invoice totals locally; already-pushed Xero invoices move to drift — staff must re-push manually |
| Statement email PDF attachment | Email attaches HTML statement only; PDF is separate download in UI |
| Scheduled statement emails | Manual email from /statements only; no monthly auto-send cron |
| COA push-back to Xero/QBO | Edits and manual accounts are local cache; changes are not written back to the accounting platform API |
| Full native ledger | No journal entries, bank rec, or standalone accounting without Xero/QBO |
Next Steps
- Xero Setup — Full accounting onboarding runbook
- Settings — Integrations and invoice generation options