How to Upload Charges with Universal CSV

Universal CSV lets you bill your clients using data from vendors that are not directly integrated with BillingBot (for example, a distributor that only sends you an Excel/CSV report each month). You teach BillingBot, once for each file format, which column holds each important piece of data, and then each month you simply upload the new file.

When to Use This Screen

Use "Universal CSV" (menu Universal CSV, screen CSV Management) when:

• A vendor or distributor sends you a CSV file with the month's charges instead of syncing automatically with BillingBot.
• You already have a file format defined (or are about to define one) and need to upload its data periodically to generate invoices.
• You need to review, update, or delete a CSV integration configuration you created earlier.

Before you start: the CSV Integration must be configured on the Integrations screen in the main menu. If it isn't, this screen will show the error "Integration is not configured".

Minimum file requirements: for BillingBot to process invoices and send them to your PSA, the file must include the company being invoiced (code and name), the product (code and name), and the Quantity, Unit Cost, and Total values, which must be numeric. If you don't have a company or product code, you can use the name in the code field as well.

What It Shows

• CSV integration list (left column): each row is a file format you have already configured, with its Integration Name (the name you gave it) and File Name (the last uploaded file). Each row has two action buttons: one green and one red.
• Configuration panel (right or left column, depending on the step): shows the detail of the selected or in-progress integration: name, delimiter character, and the field mapping (Source Company Id, Source Company Name, Source Product Id, Source Product Name, Quantity, Unit Cost, Unit Price, and Total).
• Period field (top right): indicates which month the charges you upload will be associated with. It is essential to check this before uploading a file, because the charges are tied to whatever month is selected there.
• Top buttons New Integration, Cancel Integration, and Save Charges, which appear or hide depending on which step of the process you are in.

Available Actions

• New Integration: opens the form to create a new CSV integration format (name and delimiter character).
• Green button (load charges) on a row in the list: lets you upload a new CSV file using that integration's already-saved mapping, to load the charges for the selected period.
• Red button (delete) on a row in the list: permanently deletes that CSV integration configuration. ⚠️ This action cannot be undone; the system asks you to confirm before deleting.
• Cancel Integration: cancels the creation or upload in progress and returns to the list without saving changes.
• Save Charges: saves the charges you just uploaded and mapped, leaving them ready to invoice.
• Period selector: sets the month (year-month) that the charges you upload next will be associated with.

Step-by-Step Flow

A) Create a New Integration Format (only the first time for each file type)

1. Go to the Universal CSV menu.
2. Click New Integration.
3. Enter a descriptive name in Integration Name and the character that separates the columns in your file in Delimiter (for example , or ;).
4. Click Load CSV.
5. In the window that opens, use the upload button to choose your CSV file from your computer.
6. BillingBot validates the file automatically. If everything is correct, you'll see the file's columns reflected in a table; if there are errors, they are shown in a panel so you can fix the file before continuing.
7. Click Send Data.
8. A panel appears to map each column of your file to BillingBot's fields: Source Company Id, Source Company Name, Source Product Id, Source Product Name, Quantity, Unit Cost, Unit Price (optional), and Total. In each dropdown, select the column from your file that corresponds to each field.
9. Click Create Integration to save the configuration.

B) Upload a Month's Charges (monthly use, once the integration already exists)

1. Go to the Universal CSV menu and check the Period field at the top right: select the month the charges you're about to upload belong to. This step is crucial: if you leave the wrong month selected, the charges will be saved under the wrong period.
2. In the integration list, find the matching format and click its green button.
3. Choose the month's CSV file (Browse) and wait for it to be validated.
4. Click Send Data to review the uploaded data on screen.
5. Check that the information looks correct.
6. Click Save Charges to record the charges for that period.

C) Send the Charges to Invoicing

1. Go to the Ready To Invoice menu.
2. Select the Imports CSV integration, the corresponding period, and, very important, the specific CSV integration record under which you uploaded the data (the name you gave it in step A).
3. From there, the invoices are reviewed and processed the same way as with any other integration.

Common Errors and How to Resolve Them

• "The CSV integration does not have a delimiter configured...": the integration does not have a delimiter character defined. Go to that integration's configuration and set the delimiter (for example ,, ;, or |) before uploading the file.
• "The file is empty or does not contain a valid header row.": the file has no data or is missing the header row (column names). Check the file before uploading it again.
• "The file header has no columns. Verify the delimiter is correct.": you probably chose the wrong delimiter (for example, you selected ; but the file uses ,). Fix the delimiter in the integration's configuration.
• "Duplicate column header found: ...": the file has two columns with the same name. Each column must have a unique name; fix the original file.
• "Row ...: has ... columns but the header defines ...": a row in the file has more or fewer values than the columns defined in the header. Check that row in your file (a comma or a value might be missing).
• "The file has a header but contains no data rows." / "The file has a header but all data rows are empty.": the file only has headers, with no actual data to load. Verify that you exported the correct file.
• "Error! Incomplete company id data" (or company name, product id, product name, Quantity, Unit Cost, Total): when creating the integration, you left one of the required fields unmapped. Complete the mapping for that column before continuing (Unit Price is the only optional field).
• Delete confirmation ("Are you sure you want to delete this integration?"): when you click the red button, the system always asks for confirmation because the deletion is permanent. If you're not sure, cancel.

Related Screens

• load-csv
• ready-to-invoice
• integrations