Overview

The Remittance Import tool lets you upload a spreadsheet that maps payment references to invoices. Luminous creates one payment record per unique payment reference and immediately applies it to the invoices you specify — including support for partial (short-pay) amounts. The whole process runs as a background job so you can handle large remittances without waiting.

Step 1 — Prepare your file

Create a spreadsheet file (.xlsx, .xls, or .csv) with the following column headers in the first row. Header names must match exactly (case-insensitive; spaces are treated as underscores).

ColumnRequiredDescription
PAYMENT_REFERENCE✅Unique identifier for this payment (e.g. check number, wire ref). Rows sharing the same reference are grouped into one payment.
CLIENT_ID✅Luminous customer ID. Only required on the first row of each payment group; subsequent rows for the same reference can leave it blank.
PAYMENT_AMOUNT✅Total amount of the payment. Only needed on the first row of each group.
INVOICE_ID✅Luminous invoice ID to apply this payment (or this line) to.
CURRENCYOptional3-letter currency code (e.g. USD). Defaults to USD if omitted.
PAYMENT_DATEOptionalDate the payment was received (e.g. 2026-08-15). Defaults to today if omitted.
APPLIED_AMOUNTOptionalAmount to apply to this specific invoice line. If omitted, the payment is distributed oldest-first across all listed invoices.

Save it as a genuine .xlsx file.

Example — one payment across two invoices

PAYMENT_REFERENCE | CLIENT_ID | PAYMENT_AMOUNT | INVOICE_ID | APPLIED_AMOUNT
CHK-1001          | 42        | 1500.00        | 5501       | 800.00
CHK-1001          |           |                | 5502       | 700.00

Example — multiple payments, some targeting the same invoice

PAYMENT_REFERENCE | CLIENT_ID | PAYMENT_AMOUNT | INVOICE_ID
WIRE-001          | 42        | 500.00         | 5501
WIRE-002          | 42        | 300.00         | 5501

Both payments are applied to invoice 5501 in one import action.

Step 2 — Upload the file

  1. Go to Sales → Accounts Receivable → Import Remittances.
  2. Drag and drop your remittance file (CSV or XLSX) onto the upload area, or click to browse.
  3. Luminous parses the file and shows a preview of the first 10 rows. Verify the data looks correct.
  4. Click Submit to start the import.

Step 3 — Monitor progress

After submitting, a progress bar tracks the job. Each payment group is one step. When the status reaches Done, the import is complete.

If any rows fail validation (missing required columns, invoice not found, etc.), the errors are listed on the completion screen. Fix the offending rows in your spreadsheet and re-import — already-applied payments are idempotent and will be skipped safely.

Step 4 — Verify in Apply Payments

Click Go to Apply Payments on the completion screen (or navigate to Sales → Accounts Receivable → Apply Payments) to confirm the payments are recorded and applied against the expected invoices.

Tips

  • Short-pay: Include APPLIED_AMOUNT on each line when a payment covers specific amounts per invoice rather than paying each invoice in full.
  • Multiple references, one invoice: You can import several payment references that all point to the same invoice — Luminous applies each as a separate payment record.
  • Currency: Each payment is locked to the currency you specify on its first row. Invoices in a different currency will be skipped with a currency_mismatch note.
  • Re-importing: Re-submitting a spreadsheet that was already processed is safe. The system detects already-applied (payment, invoice) pairs and skips them.