Import Metered Usage
Last updated on Sep 19, 2026
The Metered Usage import allows you to create metered usage records in Maxio directly from a CSV file. Unlike other import types, Metered Usage imports send each row to Advanced Billing through an API request rather than writing data directly to Maxio records.
Prerequisites
Review the notes below before completing a Metered Usage import:
- Your account has Advanced Billing integration enabled.
- The Metered Usage importer is enabled for your account. This is not self-serve and must be turned on by Maxio staff.
- You have metered components set up in Advanced Billing.
If you are having issues finding any of these, get in touch with our support team at support@maxio.com.
CSV fields
Prepare your CSV with the following columns before you start the import:
| Field | Required | Description |
|---|---|---|
subscription_id | Required | The subscription that the usage record belongs to. |
quantity | Required | The amount of usage to record. |
component_id | Required, unless you supply component_handle | The metered component the usage applies to. |
component_handle | Required, unless you supply component_id | The metered component's handle, as an alternative to its ID. |
price_point_id | Optional | Records the usage against a specific price point. If you supply neither price_point_id nor price_point_handle, the component's default price point is used. |
price_point_handle | Optional | The price point's handle, as an alternative to its ID. |
memo | Optional | Text sent with the usage record to Advanced Billing. |
You must supply either Component ID or Component Handle. If you supply neither, the row fails with the error Either Component ID or Component Handle must be provided.
The Advanced Billing Usage ID is returned by the API for each successful row, so it is not a column you supply.
Import metered usage
You upload the file from the Maxio Core import screen, map its columns to the Metered Usage fields, and submit it. Each mapped row is then sent to Advanced Billing as its own API request.
To create metered usage records
- Go to Admin > Import > Create.
- Under Create Records, choose Metered Usages from the list of available import types.
- Click Choose File and select your prepared CSV file.
- Click Next to continue.
- On the field mapping page, map the CSV columns to the appropriate Metered Usage fields.
- Select any desired map retention or formatting options.
- Review your field mappings for accuracy and ensure that all required fields have values.
- Click Import to submit the file.
After the import completes, the results page displays the number of successful and failed rows. You may download an error file if any rows require correction.
Import results for metered usage
Once the Metered Usage import has finished processing, the results page displays a detailed summary of the rows successfully sent to Advanced Billing and any rows that encountered errors.
During a Metered Usage import, each row is processed independently. This means the results may include a mix of successes and failures, depending on the API response from Advanced Billing.
The results page displays:
- Success Count
The number of usage records successfully created in Advanced Billing. Each successful row includes the Advanced Billing Usage ID returned by the API. - Error Count
The number of rows that failed validation or were rejected by the Advanced Billing API. Error messages appear directly in the results grid to help identify the specific issue for each row. - Downloadable Error File
If any rows fail, you can download a CSV file containing only the failed records and their corresponding error messages. After correcting the issues, you can re-upload the file to complete the import. - Partial Success Mode
Metered Usage imports always run in partial-success mode. This ensures that valid rows are processed even if other rows contain errors.
After reviewing the results, confirm the successful usage records by navigating to the associated subscription in Advanced Billing. Imported usage behaves the same as manually entered usage for billing purposes.
Related information
Before you build your file, see Format a CSV File for Import for the encoding and formatting rules the importer expects.
To see the other import types available in Maxio Core, see Understand Imports.
To import whole subscriptions into Advanced Billing rather than usage records, see Import Subscriptions from a CSV.
Still need help?
Reach out and our support team will take it from here.