Import Advanced Billing Payment Profiles

Applies to: Advanced Billing

··

Last updated on Oct 8, 2026

The Advanced Billing Payment Profiles import creates payment profiles in Advanced Billing directly from a CSV file, using each gateway's own vault token rather than a card or bank account number. Maxio Core never receives the underlying card or account number, only the token the gateway already holds for a payment method on file. The import only creates new payment profiles; it cannot update or replace one that already exists.

Prerequisites

Review the notes below before completing an Advanced Billing Payment Profiles import:

Your account has Advanced Billing integration enabled.
The Advanced Billing Payment Profiles importer is enabled for your account. This is not self-serve and must be turned on by Maxio staff.
You have the gateway's own vault token for each payment method you are importing. Advanced Billing does not contact the gateway during this import, so it cannot retrieve or verify anything beyond the token you supply.
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.

CSV fields

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

Field	Required	Description
`bank_account_holder_type`	Required for bank account rows	Either `personal` or `business`, lowercase. A row that omits it fails. Advanced Billing would otherwise silently treat any value other than exactly `business` as `personal`.
`bank_account_type`	Required for bank account rows	Either `checking` or `savings`, lowercase. A row that omits it fails. Advanced Billing would otherwise silently treat a blank value as `checking`.
`bank_name`	Required for bank account rows	The name of the bank. A row that omits it fails.
`current_vault`	Required	The handle of the gateway holding the stored payment method, for example `stripe` or `braintree_blue`.
`customer_number`	Required, unless you supply `customer_reference`	The Maxio Core Customer Number. The Customer must already exist and have synced to Advanced Billing.
`customer_reference`	Required, unless you supply `customer_number`	The Advanced Billing reference of the Customer, for use when the Customer is not in Maxio Core.
`payment_type`	Required	Which kind of payment profile to create, `credit_card` or `bank_account`. A row with a blank value, or any other value, fails.
`vault_token`	Required	The gateway's token for the stored payment method.
`billing_address`	Optional	The first line of the billing address. Whether a billing address is required depends on your Advanced Billing site settings.
`billing_address_2`	Optional	The second line of the billing address.
`billing_city`	Optional	The billing address city.
`billing_country`	Optional	The billing address country, as a two-letter ISO code.
`billing_state`	Optional	The billing address state or province.
`billing_zip`	Optional	The billing address postal code.
`card_type`	Optional, credit card rows only	The card brand, for example `visa`, `master`, `american_express`, or `discover`. This is never read from the gateway during this import, so a credit card profile imported without it has no brand to display until the Customer's payment method is updated some other way.
`customer_vault_token`	Optional	The gateway's token for the Customer. Required by the Authorize.Net, Square, Adyen, and Forte vaults.
`expiration_month`	Optional, credit card rows only	The card expiration month, as a number from 1 to 12.
`expiration_year`	Optional, credit card rows only	The four-digit card expiration year.
`first_name`	Optional	The first name on the payment method. Defaults to the Customer's first name.
`gateway_handle`	Optional	The handle of the gateway to attach the profile to. Only used on sites with more than one gateway configured.
`last_four`	Optional, credit card rows only	The last four digits of the card. This is never read from the gateway during this import, so a credit card profile imported without it has no digits to display until the Customer's payment method is updated some other way.
`last_name`	Optional	The last name on the payment method. Defaults to the Customer's last name.

Import Advanced Billing payment profiles

You upload the file from the Maxio Core import screen, map its columns to the Advanced Billing Payment Profile fields, 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.

To create Advanced Billing payment profiles

Go to Admin > Import > Create.
Under Create Records, choose Advanced Billing Payment Profiles from the list of available import types.
Click Choose File and select your prepared CSV file.
Click Next to continue.
On the field mapping page, map the CSV columns to the fields described above.
Select any desired map retention or formatting options.
Review your field mappings for accuracy and ensure every required field has a value.
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.

Import results for Advanced Billing payment profiles

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.

The results page displays:

Success Count - The number of rows reported as created or skipped (see below). Each created row includes the Advanced Billing payment profile 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 synced yet

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 payment profile.

A Customer marked Do Not Sync to Advanced Billing, or one with no email address, never reaches Advanced Billing through the sync, so its row fails rather than being skipped on every run. Correct the Customer's sync settings, or supply its Advanced Billing customer_reference instead, and re-import the row.

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, because that reference is read directly from Advanced Billing rather than depending on the Maxio Core sync.

What row errors mean

When a row fails validation, the error message in the results grid names the problem:

No Customer named: Either Customer Number or Customer Reference is required. The row sets neither customer_number nor customer_reference.
Two Customers named: Provide either Customer Number or Customer Reference, not both. The import can't tell which identifier you intended.
Fields for the wrong payment type: for example Last Four, Card Type cannot be set for a bank account. The message names every misplaced column. Card fields are rejected on a bank account row, and bank fields are rejected on a credit card row.
Missing bank field: for example Bank Name is required for a bank account. The same message pattern applies to Bank Account Type and Bank Account Holder Type.

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 import whole subscriptions into Advanced Billing rather than payment profiles for existing Customers, see Import Subscriptions from a CSV.

To decide between running a migration yourself and having the Onboarding team run it for you, see Migrate Data to Maxio.

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

Contact support