---
title: Import a Product Catalog from a CSV
url: https://docs.maxio.com/configuration/importing/import-product-catalog-from-a-csv
applies_to: Advanced Billing
updated: 2026-11-16
---

# Import a Product Catalog from a CSV

The product catalog importer creates Product Families, Products, Components, Component Price Points and Coupons in Advanced Billing from separate CSV files, one for each record type. Each Product and each Component is created with its default Price Point built inline from fields on the same row. To give a Component more Price Points than its default, such as an annual rate or a promotional rate, import them from a separate Component Price Point CSV after the Component exists.

## Prerequisites

Review the notes below before completing a product catalog import:

- Your account has Advanced Billing integration enabled.
- The product catalog importer is enabled for your account. This is not self-serve and must be turned on by Maxio staff.

If you are having issues finding any of these, get in touch with our support team at [support@maxio.com](mailto:support@maxio.com).

## Import product families first

Products, Components and Coupons reference the Product Family they belong to by its Handle rather than by an internal ID, and Advanced Billing has to already know that Handle before a Product, Component or Coupon referencing it can be created. Import your Product Family CSV first, confirm it completed, and only then import your Product, Component and Coupon CSVs.

A Product, Component or Coupon row whose `product_family_handle` doesn't match any Product Family already in Advanced Billing is never sent to Advanced Billing at all. It fails with a message naming the missing Handle, as described in [Error messages](https://docs.maxio.com/configuration/importing/import-product-catalog-from-a-csv#error-messages) below.

Component Price Points follow the same rule one level down. Each Component Price Point row names its Component by Handle, so import your Component CSV and confirm it completed before you import your Component Price Point CSV.

## CSV fields for product families

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

| Field | Required | Description |
| :--- | :--- | :--- |
| `handle` | Required | A unique identifier used to reference this Product Family in Advanced Billing. |
| `name` | Required | The display name of the Product Family. |
| `description` | Optional | A brief description of the Product Family. |

## CSV fields for products

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

| Field | Required | Description |
| :--- | :--- | :--- |
| `handle` | Required | A unique identifier used to reference this Product in Advanced Billing. Must contain only lowercase letters, numbers, hyphens, and underscores. |
| `product_family_handle` | Required | The Handle of the Product Family this Product belongs to. The Product Family must already be imported. |
| `name` | Required | The display name of the Product. |
| `description` | Optional | A brief description of the Product. |
| `price_in_cents` | Required | The price, in cents, of the Product's default Price Point. |
| `interval` | Required | The billing frequency for the default Price Point, measured in Interval Units. |
| `interval_unit` | Required | The measure of frequency for the default Price Point's Interval. Either `month` or `day`. |
| `accounting_code` | Optional | A code used for accounting purposes. |
| `request_credit_card` | Optional | Whether to request a credit card when a customer signs up for a subscription using this Product. |
| `require_credit_card` | Optional | Whether to require a credit card when a customer signs up for a subscription using this Product. |
| `trial_price_in_cents` | Optional | The price, in cents, of the trial period on the default Price Point. |
| `trial_interval` | Optional | The length of the trial period on the default Price Point, measured in Trial Interval Units. |
| `trial_interval_unit` | Optional | The measure of frequency for the default Price Point's Trial Interval. Either `month` or `day`. |
| `expiration_interval` | Optional | The length of time before a subscription on this Product expires, measured in Expiration Interval Units. |
| `expiration_interval_unit` | Optional | The measure of frequency for the default Price Point's Expiration Interval. Either `month` or `day`. |

## CSV fields for components

The Component importer creates quantity-based, metered and on/off Components, each with a default Price Point that uses the per-unit pricing scheme. Prepare your Component CSV with the following columns before you start the import:

| Field | Required | Description |
| :--- | :--- | :--- |
| `handle` | Required | A unique identifier used to reference this Component in Advanced Billing. Must start with a lowercase letter or a number, and may contain only lowercase letters, numbers, hyphens, underscores and colons. |
| `product_family_handle` | Required | The Handle of the Product Family this Component belongs to. The Product Family must already be imported. |
| `kind` | Required | The type of Component to create. One of `quantity_based`, `metered` or `on_off`. |
| `name` | Required | The display name of the Component. |
| `unit_name` | Optional | The name of the unit you charge for, such as `seat` or `call`. |
| `pricing_scheme` | Optional | The pricing scheme of the Component's default Price Point. Only `per_unit` is supported. |
| `unit_price` | Optional | The price per unit of the Component's default Price Point, for example `10.00`. |
| `accounting_code` | Optional | A code used for accounting purposes. |
| `tax_code` | Optional | A tax code used for tax calculation purposes. |
| `item_category` | Optional | The item category of the Component. One of `None`, `Business Software`, `Consumer Software`, `Digital Services`, `Physical Goods` or `Other`. |
| `description` | Optional | A brief description of the Component. |

The Component importer creates only the default Price Point for each Component. To add more per-unit Price Points to a Component, use the Component Price Point importer described below. Tiered, volume, stairstep and other pricing schemes, and prepaid usage and event-based Components, aren't supported by these importers, so create those in Advanced Billing.

## CSV fields for component price points

The Component Price Point importer adds Price Points to Components that already exist in Advanced Billing, one Price Point for each row. Each Price Point uses the per-unit pricing scheme. Prepare your Component Price Point CSV with the following columns before you start the import:

| Field | Required | Description |
| :--- | :--- | :--- |
| `component_handle` | Required | The Handle of the Component this Price Point belongs to. The Component must already be imported or created in Advanced Billing. |
| `handle` | Required | A unique identifier for this Price Point within its Component. Must start with a lowercase letter or a number, contain at least one lowercase letter, and use only lowercase letters, numbers, hyphens and underscores, up to 255 characters. Colons aren't allowed, even though Component Handles allow them. |
| `name` | Required | The display name of the Price Point. |
| `unit_price` | Required | The price per unit at this Price Point, greater than 0, for example `12.50`. |
| `pricing_scheme` | Optional | The pricing scheme of the Price Point. Only `per_unit` is supported. |
| `interval` | Optional | The billing frequency of the Price Point, measured in Interval Units. Provide it together with `interval_unit`, or leave both blank. |
| `interval_unit` | Optional | The measure of frequency for the Interval. Either `month` or `day`. Provide it together with `interval`, or leave both blank. |

The Component Price Point importer only creates Price Points. It doesn't change a Component's default Price Point or update an existing Price Point.

## CSV fields for coupons

The Coupon importer creates one Coupon for each row, as either a percentage discount or a fixed-amount discount. Prepare your Coupon CSV with the following columns before you start the import:

| Field | Required | Description |
| :--- | :--- | :--- |
| `code` | Required | The code your customers enter to redeem the Coupon. It must be unique within the Product Family and may contain only letters, numbers and the characters `%` `@` `+` `-` `_` `.`. The importer converts it to uppercase. |
| `name` | Required | The internal name of the Coupon. It isn't shown to customers. |
| `description` | Required | A brief description of the Coupon. Advanced Billing requires one, so a row without a description fails. |
| `product_family_handle` | Required | The Handle of the Product Family this Coupon belongs to. The Product Family must already be imported. |
| `percentage` | Optional | The percentage discount, greater than 0 and no more than 100. Provide either `percentage` or `amount_in_cents`, not both. |
| `amount_in_cents` | Optional | The fixed discount amount, in cents. Provide either `percentage` or `amount_in_cents`, not both. |
| `recurring` | Optional | Whether the discount also applies after the first billing period. Leave it blank or false for a one-time Coupon. Set it to true to use any of the duration columns. |
| `duration_period_count` | Optional | The number of renewal periods a recurring Coupon applies to after the initial discount, from 1 to 120. For example, 12 applies the discount at signup and on the next 12 renewals. Requires `recurring` to be true. |
| `duration_interval` | Optional | The length of each discounted period, measured in Duration Interval Units. Requires `duration_period_count` and `duration_interval_unit`. |
| `duration_interval_unit` | Optional | The measure of frequency for the Duration Interval. Either `month` or `day`. Provide it together with `duration_interval`, or leave both blank. |
| `conversion_limit` | Optional | The maximum number of times the Coupon can be redeemed, greater than 0. If you add more codes to the Coupon after the import, the limit applies to each code separately. Leave it blank for no limit. |
| `end_date` | Optional | The date the Coupon expires. Leave it blank for a Coupon that doesn't expire. |
| `stackable` | Optional | Whether the Coupon can be applied to a Subscription alongside other Coupons. |
| `compounding_strategy` | Optional | How a stackable Coupon combines with other Coupons. Either `compound` or `full-price`. Requires `stackable` to be true. |
| `allow_negative_balance` | Optional | Whether the Coupon's discount can be larger than the charge it applies to. |

The importer creates Coupons only. Restrictions to specific Products or Components, additional Coupon codes and prices in other currencies aren't supported by this importer, so set those up in Advanced Billing after the import.

The importer checks each row before sending it to Advanced Billing, and fails a row that Advanced Billing would otherwise accept but change. For example, a row that sets `duration_period_count` without setting `recurring` to true fails, rather than creating a one-time Coupon. A Coupon whose `end_date` has already passed can't be imported, because Advanced Billing doesn't accept expired Coupons.

For how stackable Coupons and compounding strategies apply to a Subscription, see <a href="https://docs.maxio.com/billing/catalog/coupons/apply-coupons-to-subscriptions" target="_blank" rel="noopener noreferrer">Apply Coupons to Subscriptions</a>.

## Import your product catalog

A sample CSV template is available for each importer. See <a href="https://docs.maxio.com/configuration/importing/run-an-import" target="_blank" rel="noopener noreferrer">Run an Import</a> for how to download one.

You upload each file from the Maxio Core import screen, map its columns to the Product Family, Product, Component, Component Price Point or Coupon fields, and submit it. Each mapped row that passes the importer's checks and isn't a duplicate is then sent to Advanced Billing as its own API request.

**To import Product Families**

1. Go to **Admin > Import > Create**.
2. Under **Create Records**, choose **Product Families** from the list of available import types.
3. Click **Choose File** and select your prepared Product Family CSV file.
4. Click **Next** to continue.
5. On the field mapping page, map the CSV columns to the Product Family 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.

Once the results page confirms the import finished, repeat the same steps for your Product CSV, choosing **Products** in step 2, for your Component CSV, choosing **Components** in step 2, and for your Coupon CSV, choosing **Coupons** in step 2. When your Component import has finished, repeat them for your Component Price Point CSV, choosing **Component Price Points** in step 2.

## Re-running an import file

Re-running the same Product Family, Product, Component, Component Price Point or Coupon file doesn't create duplicates. The Product Family, Product and Component importers match rows to existing Advanced Billing records by Handle, and the Coupon importer matches by code. A Product Family row whose Handle already exists in Advanced Billing, a Product or Component row whose Handle already exists in the Product Family named on that row, or a Coupon row whose code already exists in the Product Family named on that row, is reported as a skipped row rather than a failure, and no request is sent for it.

The Component Price Point importer matches a row to an existing Price Point by its `handle` on the Component the row names, including the Component's default Price Point and any Price Point added earlier in the same file. If that Price Point has the same pricing scheme, the same unit price and, when Advanced Billing records an interval for it, the same interval, the row is reported as skipped and no request is sent for it. If any of those values is different, the row fails and its error names the value that doesn't match, so nothing is created or changed.

Coupon codes are matched regardless of case, and archived Coupons count as existing, so a row whose code matches an archived Coupon is skipped too. A Coupon row whose code appears earlier in the same file is also skipped. Because Coupon codes are unique within a Product Family, the same code in a different Product Family creates a new Coupon there.

None of these importers supports updates. Only new Product Families, Products, Components, Component Price Points and Coupons can be created this way. If a Product Family, Product, Component or Coupon row matches an existing record, changing the row's other column values and re-importing the file doesn't update the existing record; the row is still skipped. A Component Price Point row with changed values fails instead, as described above. Make changes to an already-imported record directly in Advanced Billing.

## Error messages

The importers surface the following row-level errors in the downloadable error file:

- **Product family not found**: `Product family <handle> was not found in Advanced Billing. Please import product families first.` The `product_family_handle` on a Product, Component or Coupon row doesn't match any Product Family Advanced Billing already knows about. Import the missing Product Family first, then re-import just this row.
- **Missing or invalid values**: A row with a missing required field, a Product Handle that uses anything other than lowercase letters, numbers, hyphens, and underscores, a Component Handle that doesn't follow the format in [CSV fields for components](https://docs.maxio.com/configuration/importing/import-product-catalog-from-a-csv#csv-fields-for-components), or an interval unit other than `month` or `day` fails before any request is sent to Advanced Billing.
- **Unsupported component kind or pricing scheme**: A Component row whose `kind` isn't `quantity_based`, `metered` or `on_off`, or whose `pricing_scheme` is anything other than `per_unit`, fails before any request is sent to Advanced Billing. The message names the value in the row.
- **Invalid coupon values**: A Coupon row fails before any request is sent to Advanced Billing when it sets both or neither of `percentage` and `amount_in_cents`, uses a code character outside the allowed set, sets a duration column without setting `recurring` to true, sets `compounding_strategy` without setting `stackable` to true, or has an `end_date` that has already passed. The message names the columns involved.
- **Component not found**: `Component <handle> was not found in Advanced Billing. Please import components before price points.` The `component_handle` on a Component Price Point row doesn't match any Component in Advanced Billing. Import the Component first, then re-import this row.
- **Price point handle already in use with different values**: `A price point with handle '<handle>' already exists on this component with unit_price '<existing value>', not '<value in the row>'. Not modified.` The message names `pricing_scheme`, `interval` or `unit_price`, whichever doesn't match. Give the row a new Handle, or change the existing Price Point in Advanced Billing.
- **Invalid component price point values**: A Component Price Point row fails before any request is sent to Advanced Billing when its `handle` is missing or doesn't follow the format in [CSV fields for component price points](https://docs.maxio.com/configuration/importing/import-product-catalog-from-a-csv#csv-fields-for-component-price-points), its `unit_price` is 0 or less, its `pricing_scheme` is anything other than `per_unit`, or it sets only one of `interval` and `interval_unit`.
- **Handle taken by a record in a different family**: A Product Handle, or a Component Handle, must be unique across your entire Advanced Billing site, not only within the Product Family you're importing it into. If a row's Handle is already in use on a Product or Component in a *different* Product Family, the row fails rather than being skipped, so you don't lose track of a record that wasn't created where you expected. Give the row a Handle that isn't already in use anywhere in your site.
- **Rejected by Advanced Billing**: If Advanced Billing rejects a Component, Component Price Point or Coupon row, the error file shows Advanced Billing's own message for that row.
