Usage files

API Version

Product Catalog

Library

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 object using the upload endpoint. This returns an url.

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. Only text/csv files are supported.

Step 3: Upload the CSV file using the returned url.
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 using the retrieve_file_processing_status endpoint.

Important:

Learn more 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(,).
The file must not exceed 1 GB size or 1 million records. The lesser of the two limits applies.
The uploaded data will be processed at the rate of 10,000 events per minute.

To process more usage events than the limit mentioned above, contact support at support@chargebee.com

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, subscription_id, and usage_timestamp.
Each row must include deduplication_id, subscription_id, and 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, subscription_id, and usage_timestamp) will automatically be added to the 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, so the upload URL is not generated. The file size exceeds 1 GB. The upload succeeds, but processing is discarded. Check the status using the Retrieve file processing status endpoint. 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 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
    }
}

API Index URL GET

https://{site}.file-ingest.chargebee.com/api/v2/usage_files

id

string, max chars=36
A unique identifier for the usage file.

name

string, max chars=150
The name of the uploaded file.

mime_type

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 about the error codes.

error_reason

optional, string, max chars=500
A descriptive, human-readable message explaining the failure. Learn more about the error messages.

status

optional, enumerated string, default=queued
Current status of the usage file.

Possible values are

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.

upload_details
Show attributes [+]

optional, upload_detail
Contains details of the file upload.

id

string, max chars=36
A unique identifier for the usage file.

name

string, max chars=150
The name of the uploaded file.

mime_type

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 about the error codes.

error_reason

optional, string, max chars=500
A descriptive, human-readable message explaining the failure. Learn more about the error messages.

status

optional, enumerated string, default=queued
Current status of the usage file.

Possible values are

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.

upload_details

optional, upload_detail
Contains details of the file upload.

This endpoint returns an upload URL for uploading usage events files, allowing you to upload files in supported formats. The file is processed asynchronously, and its status can be tracked using the retrieve_file_processing_status endpoint.

Before uploading, review the following guidelines and constraints:

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.file-ingest.chargebee.com/api/v2/usage_files/upload_url \
     -u {site_api_key}:\
     -d file_name="usage_events-1743661346062.csv" \
     -d mime_type="text/csv"

copy

Click to Copy

Sample Response [ JSON ]

{
    "usage_file": {
        "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
        }
    }
}

URL Format POST

https://{site}.file-ingest.chargebee.com/api/v2/usage_files/upload_url

file_name[]

required, string, max chars=150

Name of the file being uploaded.

Note: No special characters are allowed in the file_name except for underscores _ and hyphens -.

Example:

Valid file name	Invalid file name
merchant_data.csv	merchant@data.csv
sales_report-2024.csv	sales&report-2024.csv
customer_details_file.csv	customer!details#file.csv

mime_type[]

required, string, max chars=100
Indicates the format of a file.

Note: Currently, only text/csv is supported.

usage_file

always returned
Resource object representing usage_file

Use this endpoint to get the current status and details of a usage events file.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.file-ingest.chargebee.com/api/v2/usage_files/6fa7df05-9d4a-4c29-a161-bded616459c4/processing_status \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

{
    "usage_file": {
        "id": "6fa7df05-9d4a-4c29-a161-bded616459c4",
        "name": "usage_events-1743661346062.csv",
        "mime_type": "text/csv",
        "error_code": "PARTIAL_FAILURE",
        "error_reason": "Some records in the file could not be processed successfully. Please check the failed records in the [UI/Failed Queue] for more details.",
        "status": "PROCESSED",
        "total_records_count": 5000,
        "processed_records_count": 2331,
        "failed_records_count": 2669,
        "file_size_in_bytes": 1157858,
        "processing_started_at": 1743661350150,
        "processing_completed_at": 1743661354109,
        "uploaded_by": "full_access_key_v1",
        "uploaded_at": 1743661348120
    }
}

URL Format GET

https://{site}.file-ingest.chargebee.com/api/v2/usage_files/{usage-file-id}/processing_status

usage_file

always returned
Resource object representing usage_file

Upload usage events using files

Best practices

File upload constraints

File field constraints

Validating and handling errors

Sample usage file [ JSON ]

API Index URL GET

Model Class

Usage file attributes

Consent Fields for Usage file

Custom Fields for Usage file

Retrieve usage file upload URL ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve file processing status ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL