# Usage files

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Represents a file containing usage events that has been uploaded for processing.

## Upload usage events using files

Follow these steps to upload usage event files:

**Step 1:** Request an `[usage_file](/docs/api/usage_files/usage-file-object)` object using the upload endpoint. This returns an `[url](/docs/api/usage_files/usage_file-object#upload_details)`.

**Step 2:** Create a CSV file containing the usage event records. Ensure that the file meets the expected format and complies with the [file upload constraints](/docs/api/usage_files#file_upload_constraints). Only `text/csv` files are supported.

**Step 3:** Upload the CSV file using the returned `[url](/docs/api/usage_files/usage_file-object#upload_details)`.  
Make an HTTP `PUT` request to the upload URL. Include the file in the request body as binary data (raw file content).

**Step 4:** Check the uploaded `[usage_file_status](/docs/api/usage_files/usage_file-object#status)` using the `[retrieve_file_processing_status](/docs/api/usage_files/get-uploaded-file-processing-status)` endpoint.

**Important** : [Learn more](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/ingesting-usage-from-amazon-s3) about ingesting usage events from Amazon S3.

### Best practices

-   We recommend not to create empty files which contain only header rows.
-   We recommend uploading files in batches of **100,000** events per file or lesser to ensure optimal performance.
-   We recommend ensuring that no row contains extra columns without corresponding headers.

### File upload constraints

-   File names should not contain any special characters except for underscores `_` and hyphens `-`.
-   File names must be under **150** characters and include the appropriate extensions, such as `.csv`.
-   The supported delimiter for CSV file format is **comma(,)**.

**See also**

-   [Limits for Usage-based Billing in Chargebee](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages#usage-based-billing-limits)

### File field constraints

-   Make sure your file follows the sample file format:

**deduplication\_id**

**subscription\_id**

**usage\_timestamp**

**input\_tokens**

**output\_tokens**

123e4567-e89b-12d3

Sub-01

1741156511000

100

100

987f6543-b21c-34a5

Sub-02

1741156511001

859

194

-   Learn more about `[deduplication_id](/docs/api/usage_events/create-a-usage-event#deduplication_id)`, `[subscription_id](/docs/api/usage_events/create-a-usage-event#subscription_id)`, and `[usage_timestamp](/docs/api/usage_events/create-a-usage-event#usage_timestamp)`.
    
-   Each row must include `[deduplication_id](/docs/api/usage_events/create-a-usage-event#deduplication_id)`, `[subscription_id](/docs/api/usage_events/create-a-usage-event#subscription_id)`, and `[usage_timestamp](/docs/api/usage_events/create-a-usage-event#usage_timestamp)`. Rows missing any of these fields are flagged as failed events.
    
-   Any top-level fields in the event row that are not a recognized field (`[deduplication_id](/docs/api/usage_events/create-a-usage-event#deduplication_id)`, `[subscription_id](/docs/api/usage_events/create-a-usage-event#subscription_id)`, and `[usage_timestamp](/docs/api/usage_events/create-a-usage-event#usage_timestamp)`) will automatically be added to the `[properties](/docs/api/usage_events/create-a-usage-event#properties)`.
    
    **Field Naming Guidelines**: Ensure that your file's column headers follow the required naming rules to avoid processing issues:
    
    -   **Start with:** a lowercase letter (`a-z`)
-   **May include:**
    
    -   Lowercase letters (`a-z`)
    -   Numbers (`0-9`)
    -   Underscores (`_`)

**Valid Examples**

**Invalid Examples**

`input_tokens`

`InputTokens`

`output_tokens`

`Output Tokens`

`feature_usage_1`

`123output`

`output_value`

`output@value`

`input_value`

`input-value`

### Validating and handling errors

When uploading a usage events file using the API, certain validation checks are performed. If issues are detected, the upload or processing may fail. The following sections explain the possible error scenarios and how they are handled.

Error Code

Description

`INVALID_FILE`

This error occurs in the following scenarios:

-   The file is not in a supported [MIME type](/docs/api/usage_files/get-usages-file-upload-url#mime_type), so the upload [URL](/docs/api/usage_files/usage_file-object#upload_details) is not generated.
-   The file contains invalid or corrupt content that prevents successful parsing. **Error Message:** "The file format, size, or content is invalid. Please ensure the file is in the correct format and adheres to the size limits."

`DUPLICATE_COLUMNS`

This error occurs when the file contains duplicate column headers, which must be unique. **Error Message:** "Duplicate columns found: \[list of duplicates\]. Please remove duplicates from your file before uploading again."

`RECORD_LIMIT_EXCEEDED`

This error occurs when the number of records in the uploaded file exceeds the system-defined limit. The `[limit]` placeholder specifies the maximum allowed records. **Error Message:** "The number of records exceeds the allowed limit of \[limit\]. Please reduce the number of records in the file and try uploading again."

`PARTIAL_FAILURE`

This error indicates that some records in the file failed to process, while others were processed successfully. Review the failed records in the UI or failed queue for more details. **Error Message:** "Some records in the file could not be processed successfully. Please check the failed records in the \[UI/Failed Queue\] for more details."

`COMPLETE_FAILURE`

This error indicates that all records in the uploaded file failed to process. Review the file, fix the issues, and try uploading it again. **Error Message:** "All records in the file failed to process. Please check the failed records in the \[UI/Failed Queue\] for more details."

`INVALID_COLUMNS`

This error indicates that the file contains invalid column headers. **Error Message:** "Invalid columns found: \[list of invalid headers\]. Please correct column names in your file before uploading again."

**Note**: Usage events flagged as failed appear in the **Usages** > [**Failed Events**](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/ingesting-usage-events-into-chargebee#failed_events) section of the **Admin UI Dashboard**.

## Sample Usage file

```json
{
  "id": "6fa7df05-9d4a-4c29-a161-bded616459c4",
  "name": "usage_events-1743661346062.csv",
  "mime_type": "text/csv",
  "upload_details": {
    "url": "https://cb-prod-us-e1-fileservice-temporaryfiles-store.s3.amazonaws.com/staged_file/{site}/01JR2NJ25PA7WKQCW5G6H0TR99/usage_events-1743661346062.csv?X-Amz-Security-Token=/....",
    "expires_at": 1743662040000
  }
}
```

## Usage files attributes

## Input Parameters

- `id` (required, string, max chars=36)
  A unique identifier for the usage file.

- `name` (required, string, max chars=150)
  The name of the uploaded file.

- `mime_type` (required, string, max chars=100)
  Indicates the format of a file.
  
  **Note:** Currently, only `text/csv` is supported.

- `error_code` (optional, string, max chars=50)
  A short, machine-readable code that indicates the reason for the failure. [Learn more](/docs/api/usage_files) about the error codes.

- `error_reason` (optional, string, max chars=500)
  A descriptive, human-readable message explaining the failure. [Learn more](/docs/api/usage_files) about the error messages.

- `status` (optional, enumerated string, default=queued)
  Current status of the usage file.
  Possible enum values:
    - `queued`
      The file is queued for upload.
    - `imported`
      The file has been imported.
    - `processing`
      The file is currently being processed.
    - `processed`
      The file processing is completed.
    - `failed`
      The file failed to process.

- `total_records_count` (optional, long)
  Total number of records in the file.

- `processed_records_count` (optional, long)
  Number of records that were successfully processed.

- `failed_records_count` (optional, long)
  Number of records that failed validation or import.

- `file_size_in_bytes` (optional, long)
  The size of the file in bytes.

- `processing_started_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the file processing began.

- `processing_completed_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the file processing was completed.

- `uploaded_by` (optional, string, max chars=100)
  Identifier of the user or system that uploaded the file.

- `uploaded_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the file was uploaded.

- `error_file_path` (optional, string, max chars=2000)
  Amazon S3 path in your bucket where the error file containing error codes is uploaded.

- `error_file_url` (optional, string, max chars=2000)
  Pre-signed URL for the `error_file` containing `[error_codes](/docs/api/usage_files/usage_file-object#error_code)`. The link is valid for 60 minutes.

- `upload_details` (optional, upload_detail)
  Contains details of the file upload.
  - `url` (required, string, max chars=2000)
    Pre-signed URL that allows you to upload usage events file.
  - `expires_at` (required, timestamp(UTC) in seconds)
    Expiry time of the pre-signed URL.