---
title: Import Subscriptions from a CSV
url: https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv
applies_to: Advanced Billing
updated: 2026-10-26
---
# Import Subscriptions from a CSV
The subscriptions import tool allows you to import new subscriptions into Advanced Billing from a CSV file. The tool **does not** allow you to update existing subscriptions via this method. The CSV subscription import feature is strictly for **creating new subscriptions**.
> **Important:** This is an advanced feature that is only recommended for merchants with technical experience in mapping data in CSV format. Support for this feature is limited.
## Before you start
If you do not feel comfortable with the procedures laid out below, open a support ticket or contact [support@maxio.com](mailto:support@maxio.com).
## Feature compatibility
Certain Advanced Billing features are not compatible with the subscription import tool at this time:
- Customer hierarchies
- Importing subscribers that utilize the WhoPays feature
## Sample XLSX files
Advanced Billing requires that you use one of the following example files to input data using the subscription import tool.
> Advanced Billing does not permit you to import files you have previously exported from the merchant login area, such as the subscriptions tab. In order for an existing subscription export report to be validly used for importing subscriptions, the data must be reformatted and placed in one of the spreadsheets below.
If you have the customers’ credit card details on file (usually merchants who are new to Advanced Billing):
- [Sample XLSX with Card Numbers](https://drive.google.com/uc?export=download&id=1WRQGH9LtZuo2BY_fBpWNfbCNn_rIZQa-)
If your customers’ payment details are stored in the secure vault of one of our supported gateways (new and existing Advanced Billing merchants):
- [Sample XLSX with Vault Tokens](https://drive.google.com/uc?export=download&id=1h_4Ct2L1p7jvlqfnZ4Yw6EpuKlzupgM3)
If you do not have your customers’ payment details and plan on requesting them later, or are subscribing them to a free product (new and existing merchants):
- [Sample XLSX with No Payment Profiles](https://drive.google.com/uc?export=download&id=14v4fiRaQ9lp39fnwpMbzdkG2_arJJ6WW)
> Save XLSX files as CSV with UTF-8 formatting before you upload them.
## Sample CSV files
If you prefer to work in a plain text editor rather than a spreadsheet program, start from one of the CSV versions of the same templates:
- [Sample CSV with card numbers](https://drive.google.com/uc?export=download&id=1RueXqbUPien-VQk1qFN2VDlCEWV_fL6T)
- [Sample CSV with vault tokens](https://drive.google.com/uc?export=download&id=1PZ1Usiq3ExpIrk-siob3FlQAeWIPDIA_)
- [Sample CSV with no payment profiles](https://drive.google.com/uc?export=download&id=1SEB64F6uNS178QrMWhGrL8xlF0jaDiJ3)
> Editing CSV files in Excel or Numbers can cause formatting issues. If you wish to edit the files using these programs, use the XLSX files above, and save them as CSV prior to import.
## Important notices and disclaimers
Review the following behaviors and gateway constraints before you build your import file, since several of them affect what you can include in the CSV and what happens to your customers when the import runs.
- When a subscription is imported that contains a product with a **trial period**, the trial period is omitted.
- Subscription imports create a subscription with a subscription state of either **Active** or **Canceled**, depending on whether the conditions for importing a canceled subscription are met.
- The activated date of the subscription is the date the subscription is imported. Unless you are importing a canceled subscription, set `next_billing_at` to a time in the future to delay the first renewal.
- API Users: Use the subscription [override endpoint](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/override-subscription) to align Advanced Billing data with your existing data.
- You must disable all email notifications related to subscription creation if you do not want to alert your customers that you have created the active subscription (signup emails, receipts, statements, and billing portal invitations). For canceled subscriptions, no email is sent regardless of these settings.
- We recommend that you limit the number of subscriptions in each import to 100.
- We recommend that you use the tool when our technical specialist team is available to help with any issues (normally Monday-Thursday, 9a-5p Eastern).
- A billing address cannot be provided unless vault tokens or full card numbers are provided as the billing address is stored with the payment profile. If you are not importing vault tokens or full card numbers, be sure your product settings do not require a payment method or billing address at signup. Once the import is complete, you can re-enable the required fields in your product settings so new signups must enter this information.
- Authorize.net requires the last four digits of the credit card number to process refunds. Include the last four digits of the credit card number when importing with vault tokens only.
- CyberSource requires a billing address to process successful transactions. You cannot import subscriptions without a vault token or full card number for this gateway.
- When working with credit card data in Excel, long strings of digits are converted into scientific notation. Excel always converts a long series of digits into scientific notation when you open the source data in Excel (double-clicking the file and opening it in Excel). To get around the scientific notation conversion, you have to import your CSV file into Excel and define the column of digits as *text* so that Excel does not convert it to scientific notation. In addition, Excel only records numbers up to 15 digits if they are not entered as text. Any additional digits are reset to 0.
- We do not recommend importing multiple subscriptions which use the same vault token.
## Advanced Billing overview
The following is a list of required fields for subscription creation via the import tool. They must be in CSV format.
Minimum requirements for *active* subscription creation
- `product_handle` or `product_id` (Can be found under the Setup tab, beneath the name of each product)
- `customer_first_name` (The customer’s first name - becomes the default for payment profile first name)
- `customer_last_name` (The customer’s last name - becomes the default for payment profile last name)
- `customer_email`
- `customer_id` (You may use customer ID if it exists. In this case, omit all other customer fields)
- `next_billing_at` (The first time you bill your customer - see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#date-format))
Minimum requirements for *canceled* subscription creation
- `product_handle` or `product_id` (Can be found under the Setup tab, beneath the name of each product)
- `customer_first_name` (The customer’s first name - becomes the default for payment profile first name)
- `customer_last_name` (The customer’s last name - becomes the default for payment profile last name)
- `customer_email`
- `customer_id` (You may use customer ID if it exists. In this case, omit all other customer fields)
- `canceled_at` (The time that the subscription was canceled - see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#date-format))
Required if you are importing credit card details
- `payment_profile_full_number`
- `payment_profile_cvv` (Optional)
- `payment_profile_expiration_month`
- `payment_profile_expiration_year`
- `payment_profile_card_type` (Optional, see [allowed values](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#card-types))
Required if you are importing existing vault information
- `payment_profile_current_vault` (see [allowed values](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#supported-vaults-and-token-examples))
- `payment_profile_vault_token` (see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#supported-vaults-and-token-examples))
- `payment_profile_customer_vault_token` (Only used for certain gateways such as Authorize.Net, Square (legacy only), Adyen and GoCardless)
- `payment_profile_last_four`
- `payment_profile_expiration_month`
- `payment_profile_expiration_year`
- `payment_profile_card_type` (Optional, see [allowed values](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#card-types))
Recommended for billing
- `payment_profile_first_name` (otherwise customer\_first\_name is used)
- `payment_profile_last_name` (otherwise customer\_last\_name is used)
- `payment_profile_billing_address`
- `payment_profile_billing_address_2`
- `payment_profile_billing_city`
- `payment_profile_billing_state` (see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#required-country-format))
- `payment_profile_billing_zip`
- `payment_profile_billing_country` (see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#required-country-format))
- `payment_collection_method` (see [payment collection method](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#payment-collection-method))
- `currency` (if [multi-currency](https://docs.maxio.com/getting-started/maxio-platform-basics/important-concepts/understand-multi-currency-in-advanced-billing) is enabled; the currencies must already be configured within your site)
Recommended if you also ship physical product
- `customer_address`
- `customer_address_2`
- `customer_city`
- `customer_state` (see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#required-country-format))
- `customer_zip`
- `customer_country` (see [format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#required-country-format))
- `customer_phone`
Components (optional)
[Detailed information on importing components](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#component-format). However here are examples of what works:
- `metered_component_id[123]` or `metered_component_id[123]price_point_id[1]`
- `quantity_component_id[456]` or `quantity_component_id[456]price_point_id[2]`
- `on_off_component_id[789]` or `on_off_component_id[789]price_point_id[3]`
Optional
- `customer_reference`
- `customer_vat_number` (see [format and information](https://docs.maxio.com/billing/subscriptions/customers/view-customer-information))
- `coupon_code`
- `previous_billing_at`
- `product_price_point_handle` or `product_price_point_id` (If included, the subscription is created with that specific [product price point](https://docs.maxio.com/billing/catalog/plans/setting-up-plan-price-points) instead of the default price for the product)
- `subscription_metafield_id`
- `customer_metafield_id`
- `import_mrr` (`true` or `false`, requires future `next_billing_at`, defaults to `false`)
- `activated_at` (The original date that the subscription was activated)
Additional Optional fields for canceled subscriptions
- `cancellation_message` (A message provided by the customer as to why they canceled)
- `reason_code` (The churn reason code associated with the cancellation)
*Customer references must be unique.*
## Date format
The following date formats are equivalent and work as input to `next_billing_at`, `activated_at`, `previous_billing_at`, and `canceled_at`:
`Aug 06 2030 11:34:00 -0400`
`Aug 06 2030 11:34 -0400`
`2030-08-06T11:34:00-04:00`
`8/6/2030 11:34:00 EDT`
`8/6/2030 8:34:00 PDT`
`2030-08-06T15:34:00Z`
You may also pass just a date, in which case Advanced Billing assumes the time to be noon: 2030-08-06
## Next billing at
If you enter NOW for `next_billing_at`, your customer is charged immediately upon import.
### Setup fee
Subscriptions that are created at a later date *do not* charge the initial/setup fee if created using this mechanism. If you have a product with a setup fee, you must use the value of NOW for `next_billing_at` in order to collect the setup fee.
### Trial period
Additionally, if there is a trial period on the purchased product, *the trial period is omitted*. In the case of any missed fees, due to the omitted setup fee, use the feature to **Add Charge** if you wish to include any additional fees to the subscription.
## Previous billing at
The optional `previous_billing_at` attribute is used to help backdate existing subscriptions that are being migrated from another billing management tool. It sets the `current_period_starts_at` and `activated_at` fields on the subscription. While `activated_at` is a display-only field, `current_period_starts_at` allows for the correct proration for 'existing' subscriptions.
For example, ordinarily, a subscription imported today has its billing period set to today. By passing a `previous_billing_at`, it’s possible to backfill the beginning of the period. Let’s say a subscription’s period started on Jan 1 2019 and ends on Jan 1 2020. The date today is July 6 2019. `previous_billing_at` sets the period start date on the subscription to Jan 1 2019, rather than the default behavior of July 6 2019.
The `previous_billing_at` date must be before the current time and before the specified `next_billing_at`. We recommend putting the subscription on a product whose recurring period matches the length of the subscription’s period. See [Date format](https://docs.maxio.com/configuration/importing/import-subscriptions-from-a-csv#date-format).
## Payment collection method
Advanced Billing allows you the option of importing invoice-based subscriptions. The payment collection method can be specified for each individual subscription and may consist of one of the following values: “automatic,” “invoice,” or “remittance.” If no method is specified within the CSV file, Advanced Billing uses your site defaults, but no changes need to be made to the site settings in order to import a variety of payment collection methods.
*The term “remittance” is the manual invoice billing for the Relationship Invoicing architecture. For the legacy statement architecture, use “invoice.”*
## Card types
The `payment_profile_card_type` field is optional. If supplied, it must be one of the following. The value `bogus` is also accepted, for use with the test gateway only.
- `alelo`
- `alia`
- `american_express`
- `anda`
- `bp_plus`
- `cabal`
- `carnet`
- `cartes_bancaires`
- `confiable`
- `creditel`
- `dankort`
- `diners_club`
- `discover`
- `edenred`
- `elo`
- `forbrugsforeningen`
- `hipercard`
- `jcb`
- `mada`
- `maestro`
- `maestro_no_luhn`
- `master`
- `naranja`
- `olimpica`
- `passcard`
- `routex`
- `sodexo`
- `synchrony`
- `tarjeta-d`
- `unionpay`
- `visa`
- `vr`
> Subscriptions that use PayPal or ACH as a payment method can be imported using the API instead.
> Only non-3DS cards can be imported into Stripe through a vault token.
## Supported vaults and token examples
If you are supplying vault tokens during import, you must also include the payment\_profile\_current\_vault field. This field specifies which gateway the token belongs to, and must be one of the supported values listed below.
The table below provides example vault tokens and formatting details for each supported gateway:
| **Gateway** `payment_profile_current_vault` | `vault_token` **Example** | **Where to Find It** |
| :--- | :--- | :--- |
| **Maxio Payments** `maxio_payments` or `maxp` | p1\_tok\_1234567890abcdef1234567\|1234567890abcdef1234567890abcdef `customer_vault_token`: p1\_cus\_1234567890abcdef1234567 | Importing to Maxio Payments is a process handled internally by our onboarding team. `maxio_payments` and `maxp` are two distinct Maxio Payments gateways; `maxio_payments` is no longer available to new sites. Confirm with your onboarding team which one your site actually uses before choosing a value. |
| **Adyen** `adyen` | 1415816459891180 `customer_vault_token`: chargify\_14 | The vault token is the `recurringDetailReference`, and the customer vault token is the `shopperReference`, both returned when creating a recurring contract via the Adyen API. Documentation: Adyen API Explorer *Advanced Billing–created profiles use* `chargify_{customer_id}` *as the shopperReference.* |
| **Authorize.Net** `authorizenet` | 123456789 `customer_vault_token`: 123456789 | The vault token is the `customerProfileId`, returned when creating a customer profile via the Customer Information Manager (CIM) API. Documentation: Customer Profiles |
| **Bambora** `beanstream` | A1234FE123f123456F12DF1CDA1234a1 | The vault token is the `payment_token`, generated when creating a payment profile using the Payment Profile API. Documentation: Payment APIs Overview |
| **BlueSnap** `blue_snap` | 1111\|VISA\|21112765 `customer_vault_token`: 28436055 | The vault\_token is the last-4 and card type plus the merchant managed subscription id. The customer\_vault\_token is the `vaultedShopperId`, returned when you create or retrieve a vaulted shopper, and used in API calls to charge the stored payment profile. Documentation: Create Vaulted Shopper |
| **Braintree** `braintree_blue` | 60428388 | Provide the vault\_token parameter with the value from Braintree’s “Customer ID” rather than the “Payment Method Token”. Documentation: Braintree Vault Overview |
| **Chase Paymentech Orbital** `orbital` | 123456789 | The vault token is the `TxRefNum`, returned in the response when tokenization is enabled during a transaction. Documentation: Orbital Gateway JSON Developer Guide |
| **Cybersource** `cybersource` | 1234567890123456789012 | The vault token is the `subscriptionID`, returned when creating a subscription via CyberSource's Payment Tokenization API. Documentation: Token Vault Management |
| **Elavon** `elavon` | 1234567890123456 | The vault token is obtained by sending a token request via Elavon Converge, which returns a token representing the stored payment method. Documentation: Commerce SDK Token |
| **eWAY Rapid** `eway_rapid` `eway_rapid_std` | 0000010012345678 | The vault token is the `TokenCustomerID`, returned when creating a token customer using the Rapid API. Documentation: eWay Rapid API Reference |
| **First Data** `firstdata` | 0123456789012345 | The vault token is generated by creating a TransArmor token, which represents the stored payment method. Documentation: Data Vault Tokenisation |
| **GoCardless** `gocardless` | MD000B2S6QED0V `customer_vault_token`: CU000BDK60TJWA | The vault token is the `mandate` ID, and the customer vault token is the `customer` ID, both returned when creating a mandate via the GoCardless API. Documentation: GoCardless API Reference |
| **Moneris Solutions** `moneris` | wjxVIIFcJAqKhBZ3URASTO8MO | The vault token is the `data_key`, returned when creating a profile via the Moneris Vault API. Documentation: Moneris Vault API |
| **NMI** `nmi` | 783765937 | The vault token is the `customer_vault_id`, returned when creating a customer via the NMI Customer Vault API. Documentation: NMI Customer Vault Docs |
| **PayPal Complete** `paypal_complete` | jwgvx42 | The vault token is the `id` returned when creating a payment token via the Payment Method Tokens API. Documentation: Payment Method Tokens API |
| **Pin Payments** `pin` | cus\_cAlS1vLNjRh1fFBk1-Abcf | The vault token is the `customer_token`, returned when creating a customer via the Customers API. Documentation: Pin Payments API Reference |
| **Square** `square` | ccof:uIbfJXhXETSP197M3GB `customer_vault_token`: VDKXEEKPJN48QDG3BGGFAK05P8 | The vault token corresponds to the Square Card ID (`ccof:...`), and the customer vault token corresponds to the Square Customer ID. Documentation: Square API Reference |
| **Stripe Connect** `stripe_connect` | cus\_1ie1SbGBevCW0A | The vault token is the `customer` ID, returned when creating a customer via the Stripe API. Note: Stripe 3DS cards cannot be imported through vault token; contact Stripe support for assistance. Documentation: Stripe API Reference |
| **TrustCommerce** `trust_commerce` | Z1RYBA | The vault token is the `billingid`, returned when creating a customer profile via the TrustCommerce API. Documentation: TrustCommerce API Guide (PDF) |
| **Worldpay (Vantiv/Litle)** `litle` | 1111222233334444 | The vault token is the `litleToken`, returned when registering a card via the `registerTokenRequest` in the Vantiv eCommerce XML API. Documentation: Tokenization Feature |
| **Windcave** `payment_express` | 0000000000518077 | The vault token is the `DpsBillingId`, returned when creating a tokenized billing record via the Windcave REST API. Documentation: Windcave REST API |
In some cases, if you're importing subscriptions into a site that already uses a legacy gateway (such as “PayPal Website Payments Pro (Legacy)” or “eWAY Rapid 3.1 (Legacy)”), you may use simplified vault identifiers like paypal or eway\_rapid. If you're unsure which value to use, contact support for guidance.
## Required country format
Advanced Billing requires that you use the ISO standard country codes when formatting the import file. Countries should be formatted as 2 characters. For more information, see the following Wikipedia article on ISO\_3166-1.
## Required state format
Advanced Billing requires that you use the ISO standard state codes when formatting the import file.
- US States (2 characters): [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US)
- States outside the US (2-3 characters): To find the correct state codes outside of the US, go to [ISO\_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and click on the link in the “ISO 3166-2 codes” column next to the country you wish to populate.
## Component format
*At this time we only support importing components via IDs.*
In order for the import tool to handle importing components we require the headers to be formatted in a specific way:
`kind_` then `component_id` then the id of the component between `[]`
Altogether it looks something like:
`quantity_component_id[123]`
Supported `kind_` values are:
`metered` / `quantity` / `on_off`
The `kind_`, along with the `component_id`, can be found when viewing your list of components:
*Location of component\_id and kind*
In addition to allocating to a component you can optionally pass `price_point_id[]` to allocate to a specific price point. As an example of how to include price point:
`quantity_component_id[123]price_point_id[1]`
The id for a price point can be found when editing the component itself (Catalog > Products > Component tab > click the Edit button on component)
If `price_point_id[]` isn't passed in the header, Advanced Billing uses the default price point for the component.
## Required custom fields format
Custom Fields need to be imported in a format: `resource` - customer or subscription, depending on which resource is the custom field attached to, then `metafield_id`, then `[]` with the id of the custom field inside the brackets. All together it looks like: `subscription_metafield_id[1234]` or `customer_metafield_id[4567]` Supported resources are: `subscription` and `customer`.
You can find the ID and the resource type when viewing the list of Custom Fields:
*Custom Fields ID and Resource*
If the custom field ID or resource is incorrect, the subscription and/or customer is created without the custom field that had an error.
## Example field values
The following is an example of the fields for each column of the CSV file for a basic import of subscriptions with existing tokens using the Advanced Billing test gateway.
| Field | Example value |
| :--- | :--- |
| `product_handle` | **basic** |
| `customer_first_name` | John |
| `customer_last_name` | Doe |
| `customer_email` | `johndoe@example.com` |
| `customer_address` | 123 Main Street |
| `customer_city` | Anywhere |
| `customer_state` | NY |
| `customer_zip` | 11111 |
| `customer_country` | US |
| `customer_organization` | John Doe Inc |
| `payment_profile_first_name` | John |
| `payment_profile_last_name` | Doe |
| `payment_profile_billing_address` | 123 Main Street |
| `payment_profile_billing_city` | Anywhere |
| `payment_profile_billing_state` | NY |
| `payment_profile_billing_zip` | 11111 |
| `payment_profile_billing_country` | US |
| `next_billing_at` | NOW |
| `payment_profile_current_vault` | bogus |
| `payment_profile_vault_token` | 1 |
| `payment_profile_last_four` | 2345 |
| `payment_profile_expiration_month` | 11 |
| `payment_profile_expiration_year` | 2030 |
| `payment_profile_card_type` | visa |
| `metered_component_id[123]` | 22 |
| `subscription_metafield_id[1234]` | Blue |
| `customer_metafield_id[4567]` | Orange |
## Import process
Once your CSV matches the field requirements above, you upload it from the subscriptions view and Advanced Billing processes each row in the background.
> **Important:** The system rejects all CSV files that are formatted incorrectly. The most common formatting issues are related to illegal characters such as commas or foreign symbols and characters.
**To import your subscriptions**
1. Select **Import** from the subscriptions view.
2. On the **Subscription Import History** screen, select **New Import**.
> **WARNING:** Do not import real customers while your site is in test mode.
3. Browse your computer for your CSV file, upload it, and click **Process CSV**.
The CSV can take several minutes to completely process.
## Troubleshooting
The **Subscription Import History** screen records every import you run, with columns for Uploaded At, Status, Started, Duration, Total, Completed, Successful, Failed, and Duplicates. Return to it after an import to check the outcome of each row.
Sometimes, the CSV file entered is formatted incorrectly, contains invalid headers, or is empty. In these cases, an error is returned when the CSV is initially submitted. The most common error occurs for non-UTF-8 CSV files.
If you are receiving this kind of error, it’s likely that the CSV file was opened, edited, and saved within a spreadsheet program, such as Excel or Numbers. When using these programs, use the “Export” functionality to export a new UTF-8 CSV each time any changes are made. Alternatively, a text editor can be used for smaller updates, as it maintains the UTF-8 CSV format.
Once the system has determined the file is valid, error messages are generated if any individual subscriptions fail. For example, the subscription on line one may be created successfully while the subscription on line two fails because its product handle does not exist.
> **Important:** The import job is aborted if 10 successive entries fail to create a subscription. This can happen if the data is not formatted correctly, or if the gateway declines the initial authorization or charge.
When one or more subscriptions fail, you can upload the same CSV file after making corrections. The system ignores any subscriptions which were imported successfully. There is no need to remove those entries from the CSV file.
## Get help
Open a support ticket if you require assistance. You can also reach us via email at [support@maxio.com](mailto:support@maxio.com).
To import subscriptions programmatically instead of by CSV, see the Create Subscription endpoint.