Documentation

Importing transactions

Import a generic CSV or BullionVault statement, with browser-side parsing and deal-level duplicate detection.

There are two bulk import paths:

  • CSV - upload your own spreadhseet.
  • BullionVault upload a PDF statement or the accounting-ledger CSV.

Both are parsed in your browser. The raw files are never uploaded; rows are validated and encrypted in the browser, and only normalised encrypted rows are sent to BullionFolio.

Open an import

Go to Transactions and choose one of:

  • CSV for the generic CSV importer.
  • BullionVault for PDF or accounting-ledger CSV statements.

You can import without deleting existing rows. The browser validates each row before sending it, the same way it prepares a manual entry.

Generic CSV

Columns

The header row is case-insensitive and may be in any order.

Required columns:

  • date — YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or MM/DD/YYYY.
  • type — buy or sell.
  • weight — gross weight with a unit suffix: g, gm, gms, oz, ozt, or kg. Examples: 600g, 1.1kg, 2.4oz.
  • metal — Gold, Silver, XAU, or XAG.
  • total_cost — the full amount paid, including the premium.
  • currency — USD, EUR, GBP, CHF, INR, CNY, HKD, AED, or SAR.
  • purity — gold: 24k, 22k, 18k, 14k, or the decimal equivalents 1.0, 0.9167, 0.75, 0.5833; silver: 0.9999, 0.999, 0.995, 0.925.

Optional columns:

  • premium_paid — the commission or premium portion of the total. Defaults to 0.
  • vault — one of the supported vault names. Defaults to Physical.
  • location — free text, such as a shelf or drawer.

Supported vault names: Physical, Bank Locker, BullionVault, The Safe House (Silver Bullion Group), Brinks, Loomis Intl, Money Metals Depository, Malca-Amit, The Reserve, Summit Metals, GoldCore, BullionStar, Swiss Gold Safe, and Online Vault. Matching is case-insensitive.

Example

date,type,weight,metal,total_cost,currency,premium_paid,purity,vault,location
2024-01-15,buy,600g,Gold,5200,USD,200,24k,Physical,Shelf A
2024-02-20,buy,1.5oz,Silver,45,USD,5,0.999,BullionVault,
2024-03-10,sell,2.4oz,Gold,2800,USD,0,22k,Physical,

Use Download Template CSV in the import dialog to get a working file with examples.

Import steps

  1. Select the CSV file.
  2. Wait for browser-side parsing.
  3. Review the preview. Valid rows have a check mark; invalid rows have a cross and an error.
  4. Choose Import N transactions.

Only valid rows are sent. Invalid rows are excluded and shown with the reason, so you can fix the file and import again.

The import limit is 5,000 rows per batch. Larger batches are rejected.

Duplicate behaviour

Generic CSV rows do not contain a BullionVault deal ID, so they are not deduplicated. Importing the same generic CSV twice creates duplicate transactions.

If that happens, filter or select the extra rows and delete them from the ledger.

Lot IDs

The generic CSV format has no lot_id column. Import first, then select the rows and use the batch bar to set a lot ID.

BullionVault statements

The BullionVault importer accepts multiple PDF and CSV files in one selection.

PDF deal lists

The parser reads the Deal list section and extracts each completed deal.

  • Gold is stored as 24k and silver as .999, because the statement deal list does not expose a purity field.
  • The vault is set to BullionVault, and the location is set to BullionVault plus the statement’s vault name.
  • Deposits, withdrawals, page headers, and other statement sections are ignored.
  • Incomplete or malformed deal entries are skipped and reported as warnings.

A PDF without a Deal list section, or one with no completed deals, cannot be imported.

Accounting-ledger CSV

The BullionVault CSV path expects the accounting-ledger format, not the generic CSV format.

  • Deals are identified by the description text and paired into a currency row and a bullion row.
  • The premium is set to 0, because this ledger format does not include the commission.
  • Incomplete pairs and unsupported currencies are skipped.
  • The vault is BullionVault and the location comes from the metal description.

Duplicate detection

BullionVault imports are matched by deal ID.

  • Deals already in your portfolio are marked Imported and excluded.
  • The server enforces the same deal-ID uniqueness, so re-importing a statement does not create duplicate deals.
  • The preview shows how many deals are new and how many already exist.

The 5,000-row batch limit also applies to BullionVault imports.

Import steps

  1. Choose the PDF or CSV statements.
  2. Wait for parsing.
  3. Review each file’s deal count, duplicate count, and skipped count.
  4. Read any warnings.
  5. Choose Import N transactions.

The result reports inserted, skipped, and rejected rows.

After the import

  • Transactions refresh automatically and the new rows appear in the ledger.
  • Portfolio values, composition, and history include the imported rows.
  • Imported transaction payloads are encrypted before they are sent to the server.
  • There is no bulk undo. To remove an import, select the rows and use Delete Selected.

Troubleshooting imports

  • Missing required column — add the exact header name. Header names are case-insensitive but must match otherwise.
  • CSV has no data rows — the file has a header but no complete rows, or rows have fewer cells than the header.
  • Invalid date, weight, metal, purity, currency, or vault — fix the value in that row. The preview shows the specific error.
  • Unsupported file type — use .csv or .pdf; other extensions are rejected before parsing.
  • No Deal list section / no transactions found — confirm the PDF is a BullionVault statement with a completed deal list, or use the accounting-ledger CSV.
  • Rows skipped — incomplete deal entries or unpaired ledger rows are skipped; warnings show the file and reason.
  • Too many rows — split the import into batches of 5,000 or fewer.
  • Duplicates after a generic CSV import — generic rows are not deduplicated; delete the repeated rows.
← All guides