Import Advanced Billing Subscriptions

The Subscriptions import creates new subscriptions directly in Advanced Billing from a CSV file, mapped and submitted from the Maxio Core import screen. Each mapped row is sent to Advanced Billing as its own API request. The import only creates new subscriptions; it cannot update one that already exists.

This is a different tool from Import Subscriptions from a CSV, which uploads a file directly within Advanced Billing's own Subscriptions view using Advanced Billing's own XLSX/CSV templates. This importer instead runs from the Maxio Core import screen, the same screen you use for Customers, Transactions, and the other Maxio Core import types, and it maps your file to a fixed set of columns rather than to Advanced Billing's own template.

Prerequisites

Review the notes below before completing a Subscriptions import:

• Your account has Advanced Billing integration enabled.
• Each Customer the file names already exists in Maxio Core and has synced to Advanced Billing, or you have that Customer's Advanced Billing reference instead.

If you are having trouble finding any of these, contact support@maxio.com.

Prepare your CSV file

Prepare your CSV with the following columns before you start the import. Every field is optional in the field mapping screen, but a row that leaves out a combination the API needs fails with a specific message, described in What row errors mean below.

Add components to a subscription

You can allocate up to five components to the new subscription, using five fixed column groups: component_1_* through component_5_*. Each slot takes the same six columns, used only when the slot is in use:

A component named by Handle resolves its kind from Advanced Billing automatically. A component named by ID resolves its kind from the Maxio Core catalog mirror, so a component created in Advanced Billing moments before the import may not have synced into that mirror yet; name it by Handle instead if you need to import it right away.

After the subscription is created, the importer checks that each component you requested was applied. A row fails, even though the subscription itself was created, when:

• A requested component did not apply to the subscription at all.
• A component landed with a different quantity than the one you asked for.

The failure message warns that the subscription was not rolled back. Fix the component allocation directly in Advanced Billing rather than re-running the row. Re-running a row without a Reference creates a duplicate subscription, and a row with a Reference is skipped on a re-run, which does not fix the components either.

The quantity check is skipped for metered and event-based components, and for any component whose allocated quantity Advanced Billing does not return, which includes a component named by an ID that has not yet synced into the catalog mirror. The check that the component was applied at all still runs.

Import Advanced Billing subscriptions

You upload the file from the Maxio Core import screen, map its columns to the fields described above, and submit it, the same way as any other Maxio Core import. Each mapped row is then sent to Advanced Billing as its own API request.

Important: This import cannot set a first billing date. When a row creates a subscription, Advanced Billing assesses and charges any trial or initial charges at the moment the subscription is created. If the card cannot be charged, the subscription is not created, so that row fails.

To import Advanced Billing subscriptions from a CSV file

1. Go to Admin > Import > Create.
2. Under Create Records, choose Subscriptions 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 fields described above.
6. Select any desired map retention or formatting options.
7. Review your field mappings for accuracy.
8. Click Import to submit the file.

After the import completes, the results page displays the number of successful and failed rows, and skipped rows count as successful. You may download an error file if any rows require correction.

Review the import results

Each row is processed independently, so results can include a mix of created, skipped, and failed rows depending on the state of the Customer it names and the response from the Advanced Billing API.

• Success Count - The number of rows reported as created or skipped. Each created row includes the Advanced Billing subscription 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 error messages. After correcting the issues, you can re-upload the file to complete the import.
• Partial Success Mode - This import always runs in partial-success mode, so valid rows are processed even when other rows contain errors.

What happens when a Customer has not yet synced

A Customer reaches Advanced Billing on its own sync schedule, not at the moment it is created in Maxio Core, so a Customer created minutes before the import runs may have no Advanced Billing record yet. A row naming that Customer by customer_number reports Record Skipped rather than failing, and sends no request to Advanced Billing. Re-run the same file after the Customer has synced, and the row creates its subscription.

This skip only applies to a row that identifies its Customer by customer_number. A row that identifies its Customer by customer_reference is never skipped for this reason, because that reference is read directly from Advanced Billing rather than depending on the Maxio Core sync.

Re-run an import file

Mapping a CSV column to Reference sets Advanced Billing's own reference field on the new subscription, so it can be found and updated later. It also makes it safe to re-upload the same file after a partial failure, or just to confirm the results: a row whose Reference was already used, on an earlier run of the same row, no longer fails outright.

When a create request fails because Advanced Billing reports the reference as already taken, the importer looks that reference up in Advanced Billing and checks whether the subscription it finds is plausibly this row's own earlier result, by comparing the Customer and, when the row specifies one, the Product:

• If the Customer and Product match (or only the Customer, on a row importing a productless subscription), the row is reported as Record Skipped rather than failed, and its record key points at that existing subscription. No duplicate subscription is created.
• If the lookup finds a subscription that belongs to a different Customer or a different Product, the reference collided with someone else's subscription rather than this row's own re-run. The row fails, with a message naming the conflicting subscription's ID, Customer, and Product so you can tell the two apart and choose a different reference.
• If the lookup itself fails (for example, a network error), the row fails with Advanced Billing's original "Reference: must be unique" message, since an unconfirmed collision can't be reported as a success.

What row errors mean

When a row fails validation before any request is sent to Advanced Billing, the error message in the results grid names the problem:

• No Customer named: Either Customer Number or Customer Reference must be provided. The row sets neither column.
• Product named twice: Provide only one of Product ID or Product Handle, not both.
• Price point named twice: Provide only one of Product Price Point ID or Handle, not both.
• Automatic collection with no payment profile: Payment Collection Method is 'automatic', which requires an existing Payment Profile ID.
• Component named twice, or not at all: for a given component slot, Component N: provide only one of ID or Handle, not both or Component N: either ID or Handle must be provided.
• Component price point or price named twice: Component N: provide only one of Price Point ID or Handle, not both or Component N: provide only one of a custom price or a price point, not both.
• Starts At with no Activated At on a non-invoice-centric site: Starts At is only honored on invoice-centric-billing sites, and this site is not invoice-centric. Use Activated At (and Canceled At for historical churn) to backdate the subscription instead. A row that also has Activated At does not fail, and Starts At is ignored.
• Customer not found: Missing customer number <number>. Please import this customer first.
• Customer reference not found: Customer reference <reference> was not found in Advanced Billing. Please confirm the customer has been synced.

Any other error, including a rejected field value or a conflicting Reference, is reported using Advanced Billing's own message, or the reference-conflict message described in Re-running an import file above.

Related information

Before you build your file, 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 bulk-create the Products and Product Families a subscription's Product Handle refers to, see Import a Product Catalog from a CSV.

To create payment profiles by gateway vault token for a Customer to reference from Payment Profile ID, see Import Advanced Billing Payment Profiles.