Import a Product Catalog from a CSV
Applies to: Advanced Billing
Last updated on Nov 16, 2026
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.
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 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 Apply Coupons to Subscriptions.
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, 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
- 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, 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.Theproduct_family_handleon 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, or an interval unit other than
monthordayfails before any request is sent to Advanced Billing. - Unsupported component kind or pricing scheme: A Component row whose
kindisn'tquantity_based,meteredoron_off, or whosepricing_schemeis anything other thanper_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
percentageandamount_in_cents, uses a code character outside the allowed set, sets a duration column without settingrecurringto true, setscompounding_strategywithout settingstackableto true, or has anend_datethat 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.Thecomponent_handleon 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 namespricing_scheme,intervalorunit_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
handleis missing or doesn't follow the format in CSV fields for component price points, itsunit_priceis 0 or less, itspricing_schemeis anything other thanper_unit, or it sets only one ofintervalandinterval_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.
Still need help?
Reach out and our support team will take it from here.
