---
title: Import Metered Usage
url: https://docs.maxio.com/configuration/importing/import-metered-usage
applies_to: "Advanced Billing, Maxio Core"
updated: 2026-09-23
---

# Import Metered Usage

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](mailto:support@maxio.com).

## CSV fields

Prepare your CSV with the following columns before you start the import:

| Field | Required | Description |
| :--- | :--- | :--- |
| `subscription_id` | Required | The ID or reference of 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**

1. Go to **Admin > Import > Create**.
2. Under **Create Records**, choose **Metered Usages** from the list of available import types.
3. Click **Choose File** and select your prepared CSV file.
4. Click **Next** to continue.
5. On the field mapping page, map the CSV columns to the appropriate Metered Usage fields.
6. Select any desired map retention or formatting options.
7. Review your field mappings for accuracy and ensure that all required fields have values.
8. 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.

## What subscription and component error messages mean

When a row fails because Advanced Billing can't find the subscription or component you specified, the error message names what it was able to confirm:

- **Subscription not found**: `Subscription 20 was not found in Advanced Billing.` The value in `subscription_id` doesn't match the ID or reference of any subscription in Advanced Billing.
- **Component not found**: `Component handle missing-handle was not found in Advanced Billing.` The `component_handle` you supplied doesn't match any component in your Advanced Billing site's catalog. This message only appears for a component handle. A missing component ID returns the last message in this list instead.
- **Component belongs to a different product family**: `Component ID 555 was not found on subscription 30. The component belongs to a different product family.` The component exists, but not in the product family the subscription belongs to. Use a component from that product family instead.
- **Cause could not be confirmed**: `Component ID 555 was not found on subscription 30.` Advanced Billing couldn't confirm which of the causes above applies. Check both the subscription and component values before re-importing the row.

If you supply both `component_id` and `component_handle`, the importer uses `component_id`, and the error message names the component ID. To get the most specific error message for a component, identify it by `component_handle`.

If `subscription_id` is an all-numeric value, Advanced Billing always looks it up as a subscription ID and never falls back to matching it against a subscription's reference. If that lookup fails and the value matches a subscription's reference instead, the error message says so and asks you to use the subscription's ID.