Settings
API Version
Product Catalog
Library

Usage files

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_upload_status endpoint.

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

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 upload 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."

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

Model Class

 

      Usage file attributes
      
 
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
 
 
queuedThe file is queued for upload.importedThe file has been imported.processingThe file is currently being processed.processedThe file processing is completed.
 
 Show all values[+]
 
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 id
 

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

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

          string, max chars=100
 Indicates the format of a file. 
Note: Currently, only text/csv is supported.
 
 
error_code 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 error_reason
 

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

          optional, enumerated string, default=queued
 Current status of the usage file. 
 
Possible values are
 
 
queuedThe file is queued for upload.importedThe file has been imported.processingThe file is currently being processed.processedThe file processing is completed.
 
 Show all values[+]
total_records_count total_records_count
 

          optional, long
 Total number of records in the file. 
 
processed_records_count processed_records_count
 

          optional, long
 Number of records that were successfully processed. 
 
failed_records_count failed_records_count
 

          optional, long
 Number of records that failed validation or import. 
 
file_size_in_bytes file_size_in_bytes
 

          optional, long
 The size of the file in bytes. 
 
processing_started_at processing_started_at
 

          optional, timestamp(UTC) in seconds
 Timestamp when the file processing began. 
 
processing_completed_at processing_completed_at
 

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

          optional, string, max chars=100
 Identifier of the user or system that uploaded the file. 
 
uploaded_at uploaded_at
 

          optional, timestamp(UTC) in seconds
 Timestamp when the file was uploaded. 
 
upload_details 
 

          optional, upload_detail
 Contains details of the file upload. 
 
 
 
Consent Fields for Usage file
 
 
Custom Fields for Usage file
 
  

      Upload usage events file
      
  
 


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_upload_status endpoint.


 
Before uploading, review the following guidelines and constraints:
  
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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
    
 
Method
 
 
Input Parameters
 
  
 
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.
 
 
 
    
 
Returns
 
usage_file  usage_file
 

      always returned 
 Resource object representing usage_file
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/usage_files/123x
    

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

        Sample Request
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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}/status
    
 
Method
 
  
   
 
    
 
Returns
 
usage_file  usage_file
 

      always returned 
 Resource object representing usage_file
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/usage_files/123x