Beta » Wallets track balances in tokens, credits, or dollars, automatically as they are used.Learn more
New » Metering turns raw usage events into billable quantities on a subscription.Learn more
/

Help Center › Configuration › Importing

Import a Product Catalog from a CSV

Applies to: Advanced Billing

··View as Markdown·

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:

FieldRequiredDescription
handleRequiredA unique identifier used to reference this Product Family in Advanced Billing.
nameRequiredThe display name of the Product Family.
descriptionOptionalA brief description of the Product Family.

CSV fields for products

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

FieldRequiredDescription
handleRequiredA unique identifier used to reference this Product in Advanced Billing. Must contain only lowercase letters, numbers, hyphens, and underscores.
product_family_handleRequiredThe Handle of the Product Family this Product belongs to. The Product Family must already be imported.
nameRequiredThe display name of the Product.
descriptionOptionalA brief description of the Product.
price_in_centsRequiredThe price, in cents, of the Product's default Price Point.
intervalRequiredThe billing frequency for the default Price Point, measured in Interval Units.
interval_unitRequiredThe measure of frequency for the default Price Point's Interval. Either month or day.
accounting_codeOptionalA code used for accounting purposes.
request_credit_cardOptionalWhether to request a credit card when a customer signs up for a subscription using this Product.
require_credit_cardOptionalWhether to require a credit card when a customer signs up for a subscription using this Product.
trial_price_in_centsOptionalThe price, in cents, of the trial period on the default Price Point.
trial_intervalOptionalThe length of the trial period on the default Price Point, measured in Trial Interval Units.
trial_interval_unitOptionalThe measure of frequency for the default Price Point's Trial Interval. Either month or day.
expiration_intervalOptionalThe length of time before a subscription on this Product expires, measured in Expiration Interval Units.
expiration_interval_unitOptionalThe 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:

FieldRequiredDescription
handleRequiredA 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_handleRequiredThe Handle of the Product Family this Component belongs to. The Product Family must already be imported.
kindRequiredThe type of Component to create. One of quantity_based, metered or on_off.
nameRequiredThe display name of the Component.
unit_nameOptionalThe name of the unit you charge for, such as seat or call.
pricing_schemeOptionalThe pricing scheme of the Component's default Price Point. Only per_unit is supported.
unit_priceOptionalThe price per unit of the Component's default Price Point, for example 10.00.
accounting_codeOptionalA code used for accounting purposes.
tax_codeOptionalA tax code used for tax calculation purposes.
item_categoryOptionalThe item category of the Component. One of None, Business Software, Consumer Software, Digital Services, Physical Goods or Other.
descriptionOptionalA 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:

FieldRequiredDescription
component_handleRequiredThe Handle of the Component this Price Point belongs to. The Component must already be imported or created in Advanced Billing.
handleRequiredA 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.
nameRequiredThe display name of the Price Point.
unit_priceRequiredThe price per unit at this Price Point, greater than 0, for example 12.50.
pricing_schemeOptionalThe pricing scheme of the Price Point. Only per_unit is supported.
intervalOptionalThe billing frequency of the Price Point, measured in Interval Units. Provide it together with interval_unit, or leave both blank.
interval_unitOptionalThe 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:

FieldRequiredDescription
codeRequiredThe 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.
nameRequiredThe internal name of the Coupon. It isn't shown to customers.
descriptionRequiredA brief description of the Coupon. Advanced Billing requires one, so a row without a description fails.
product_family_handleRequiredThe Handle of the Product Family this Coupon belongs to. The Product Family must already be imported.
percentageOptionalThe percentage discount, greater than 0 and no more than 100. Provide either percentage or amount_in_cents, not both.
amount_in_centsOptionalThe fixed discount amount, in cents. Provide either percentage or amount_in_cents, not both.
recurringOptionalWhether 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_countOptionalThe 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_intervalOptionalThe length of each discounted period, measured in Duration Interval Units. Requires duration_period_count and duration_interval_unit.
duration_interval_unitOptionalThe measure of frequency for the Duration Interval. Either month or day. Provide it together with duration_interval, or leave both blank.
conversion_limitOptionalThe 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_dateOptionalThe date the Coupon expires. Leave it blank for a Coupon that doesn't expire.
stackableOptionalWhether the Coupon can be applied to a Subscription alongside other Coupons.
compounding_strategyOptionalHow a stackable Coupon combines with other Coupons. Either compound or full-price. Requires stackable to be true.
allow_negative_balanceOptionalWhether 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

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

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

Contact support