Import a Product Catalog from a CSV

Applies to: Advanced Billing · Maxio Core

··

Last updated on Oct 7, 2026

The product catalog importer creates Product Families and Products in Advanced Billing from two separate CSV files. Each Product is created with its default Price Point built inline from fields on the same row, so there is no separate price-point file to prepare.

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.

Import product families before products

Products 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 referencing it can be created. Import your Product Family CSV first, confirm it completed, and only then import your Product CSV.

A Product 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 below.

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`.

Import your product catalog

A sample CSV template is available for each importer. See Run an Import for how to download one.

You upload each file from the Maxio Core import screen, map its columns to the Product Family or Product fields, and submit it. Each mapped row is then sent to Advanced Billing as its own API request.

To import Product Families

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

Once the results page confirms the import finished, repeat the same steps for your Product CSV, choosing Products in step 2.

Re-running an import file

Both importers match rows to existing Advanced Billing records by Handle, so re-running the same Product Family or Product file doesn't create duplicates. A Product Family row whose Handle already exists in Advanced Billing, or a Product row whose Handle 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.

Neither importer supports updates. Only new Product Families and Products can be created this way. If a Product Family row's Handle already exists, or a Product row's Handle already exists in the Product Family named on that row, changing the row's other column values and re-importing the file does not update the existing record; the row is still skipped. Make changes to an already-imported Product Family or Product 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 before products. The product_family_handle on a Product 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, or an interval unit other than month or day fails before any request is sent to Advanced Billing.
Handle taken by a product in a different family: A Product 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 in a different Product Family, the row fails rather than being skipped, so you don't lose track of a Product that wasn't created where you expected. Give the row a Handle that isn't already in use anywhere in your site.

Before you build your files, 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 create a Product one at a time instead of in bulk, see Create Products.

Still need help?
Reach out and our support team will take it from here.

Contact support