> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/integrations/data-imports/usage-event-ingestion/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Data Imports: Event File Uploads

Backfill usage events in bulk by uploading CSV files. Use this when migrating historical usage into Solvimon, or when catching up after a gap in your event pipeline.

---

## Why this matters

File uploads are primarily intended to backfill data: importing historical usage during a migration, or repairing a gap after an outage. For ongoing, real-time usage reporting, use the [Event Ingestion API](/platform-guides/meter-and-event-design/usage-events/event-ingestion-api) instead; it validates and matches events as they happen.

## How it works

Every event you ingest is matched to a [meter](/platform-guides/meter-and-event-design/meter), and every field that meter expects must be populated for the event to be accepted. Because the required columns depend on the meter, Solvimon generates a CSV template per meter with the correct headers: customer reference, event reference, timestamp, and the meter's value and property references.

You download the template, fill it with your event data, and upload it as a file. Solvimon processes the file line by line; each valid line becomes a usage event, and invalid lines are reported so you can correct and re-upload them. The same validation applies as with API ingestion.

## Implementation

### Via API

#### Download the CSV template for your meter

Retrieve the template with the [meter data file](https://docs.solvimon.com/api-docs/configuration-api/meters/get-meters-by-resource-id-or-reference-meter-data-file) endpoint:

**`Download template`**

```bash Download template
curl https://test.api.solvimon.com/v1/meters/{meter_id}/meter-data-file \
  -H "X-API-KEY: <apiKey>"
```

The response is a CSV file containing the headers required for the meter.

You can also obtain this file by [navigating to the file tab in Desk and selecting upload](https://desk.solvimon.com/files/upload). After selecting a meter, an option will appear for downloading the template CSV.

![Meter template download from file upload](/builds/solvimon/docs/fern/pages/solvimon-guides/integrations/data-imports/images/usage-events-upload/download-template.png "CSV template download for a specific meter")

For example:

**`Template response`**

```csv Template response
customer_reference,pricing_plan_subscription_id (optional),pricing_plan_subscription_reference (optional),reference (unique),timestamp (optional),meter_value.reference.event_count
```

The exact headers depend on the meter's values and properties. Headers not marked as optional are required.

#### Fill the template with your event data

Add one row per usage event. Keep the template's column headers and ordering unchanged, and make sure every event reference is unique. See [timestamp formatting](/platform-guides/for-developers/timestamp-formatting) for the expected timestamp format.

#### Upload the file

Upload the completed CSV with the [create file](https://docs.solvimon.com/api-docs/event-api/files/post-files) endpoint. The file content is sent BASE64 encoded, and `meter_data.meter_id` links the file to the meter it should be ingested against:

**`Upload file`**

```bash Upload file
curl -X POST https://test.api.solvimon.com/v1/files \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "METER_DATA",
    "file_name": "usage-backfill-2026-06.csv",
    "content_type": "text/csv",
    "content": "Y3VzdG9tZXJfcmVmZXJlbmNlLGV2ZW50X3JlZm...",
    "meter_data": {
      "meter_id": "metr_61Sx9pqJnwo42rzGV7past"
    }
  }'
```

**`Response`**

```json Response
{
  "object_type": "file",
  "id": "file_51Qx2pqJnwo42rzGV7abcd",
  "file_name": "usage-backfill-2026-06.csv",
  "type": "METER_DATA",
  "status": "CREATED",
  "number_of_lines": 1250,
  "created_at": "2026-06-30T09:41:00Z"
}
```

#### Verify processing

Poll the [file status](https://docs.solvimon.com/api-docs/event-api/files/get-files-by-resource-id) until it reaches `DONE`:

**`Check file status`**

```bash Check file status
curl https://test.api.solvimon.com/v1/files/{file_id} \
  -H "X-API-KEY: <apiKey>"
```

If the status is `ERROR`, retrieve the individual [file lines](https://docs.solvimon.com/api-docs/event-api/files/get-files-by-resource-id-lines) to see which rows failed and why:

**`Inspect failed lines`**

```bash Inspect failed lines
curl https://test.api.solvimon.com/v1/files/{file_id}/lines \
  -H "X-API-KEY: <apiKey>"
```

Successfully processed events appear on the Events page in Desk, matched to their meter.

### Via Desk

The same flow is available in Desk under **Files → Upload file** ([desk.solvimon.com/files/upload](https://desk.solvimon.com/files/upload)): selecting a meter shows a card from which you can download that meter's template, and the upload screen tracks the processing status of each file. See the [usage file uploads guide](/platform-guides/meter-and-event-design/usage-events/file-uploads) for the full Desk walkthrough.

## CSV formatting

Solvimon assumes the following CSV formatting. If your files are formatted differently, contact us before uploading.

| CSV formatting property | Description                                                                                                                                                                |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Delimiter               | The character delimiting individual cells in the CSV data. This may only be a 1-character string. For tab-delimited data enter `\\t`. By default we assume this to be `,`. |
| Double Quote            | Whether two consecutive quote characters within a quoted value represent a single quote character. By default we assume this to be the case.                               |
| Encoding                | The character encoding of the CSV data. By default we assume this to be `utf8`.                                                                                            |
| Escape Character        | The character used for escaping special characters. By default we disallow escaping.                                                                                       |
| False Values            | A set of case-sensitive strings that should be interpreted as false values. By default this is set to the following set: `n`, `no`, `f`, `false`, `off`, `0`.              |
| True Values             | A set of case-sensitive strings that should be interpreted as true values. By default this is set to the following set: `y`, `yes`, `t`, `true`, `on`, `1`.                |
| Null Values             | A set of case-sensitive strings that should be interpreted as null values. By default we interpret `NA` as a null value.                                                   |
| Quote Character         | The character used for quoting CSV values. By default we assume this to be using double quoting `"`.                                                                       |

## Edge cases

* **Custom column names and ordering.** If you can't produce files matching the template exactly, contact us to set up a custom mapping so your files are processed according to your own format.
* **Backfilling near a billing period close.** Usage can only be ingested while the invoice for that period is still editable. If you are backfilling data for a period that is about to close, review the [timing considerations](/platform-guides/meter-and-event-design/usage-events/file-uploads#timing-of-usage-ingestion--billing-periods) before uploading.

> **Warning**
>
> Do not change the column headers from the template. The headers are how Solvimon maps your data to the meter; a file with modified headers will not be accepted.

---