subscription imports.md
Bulk Importing Subscriptions
Instead of creating subscriptions one by one, you can import multiple subscriptions at once with a CSV file in the Finix Dashboard. During the import process, Finix provides a link to download a sample template (CSV) to help format your data.
Pre-requisites
- You must have a subscription plan created before you can import subscriptions. At this time, you cannot import subscriptions without providing a
subscription_plan_id. - You must have the
identity_idand paymentinstrument_idfor the subscriber.
Getting Started
- From the Subscriptions page, click the options (...) drop-down and select Bulk Import CSV.
- A Select Merchant Account popover displays.
- Select a Merchant Account.
- Click Proceed.
- An Import Subscriptions page displays.
- Follow the instructions to prepare your subscription import file, including downloading the sample template (CSV) and filling in the fields.
CSV File Requirements
The following table shows the required and optional columns for importing subscriptions from an existing plan.
Currently, you can only import subscriptions that were created from subscription plans. For each subscription, you need to provide a subscription_plan_id.
| Column Name | Type | Description |
|---|---|---|
billing_overrides. collection_method |
string, optional | - The method by which subscription payments are collected. Currently, automatically billing the Payment Instrument is the only method available. - Example: BILL_AUTOMATICALLY |
billing_overrides. send_invoice |
boolean, optional | - Whether to send the user an invoice. - Example: true |
billing_overrides. send_receipt |
boolean, optional | - Whether to send the user a receipt. - Example: true |
buyer_details. identity_id |
string, required | - The identity ID of the subscriber. - Example: IDtEnKsZyJNUGK83ZTx4C45S |
buyer_details. instrument_id |
string, required | - The ID of the Payment Instrument from which the subscription payments get debited. - Example: PImXAVgkKVshKWWHUk4xXbve |
buyer_details. requested_delivery_methods. email_destinations |
string, optional | - Email address(es) where receipts should be sent. Multiple values may be separated by a semicolon. - Example: subscriber@example.com |
buyer_details. requested_delivery_methods. sms_destinations |
string, optional | - Phone number(s) where receipts should be sent via SMS. Multiple values may be separated by a semicolon. - Example: 2348765431 |
buyer_details. shipping_address. city |
string, optional | - City (max 20 characters). - Example: Middletown |
buyer_details. shipping_address. country |
string, optional | - 3-letter country code. - Example: USA |
buyer_details. shipping_address. line1 |
string, optional | - First line of the address (max 35 characters). - Example: 324 Oak Avenue |
buyer_details. shipping_address. line2 |
string, optional | - Second line of the address (max 35 characters). - Example: Apartment 7 |
buyer_details. shipping_address. postal_code |
string, optional | - Zip or Postal code (max 7 characters). - Example: 19734 |
buyer_details. shipping_address. region |
string, optional | - 2-letter State code. - Example: DE |
currency |
string, required | - ISO 4217 3-letter currency code. At this time, the only currencies supported are USD and CAD. - Example: USD |
linked_to |
string, required | - The ID of the Merchant resource that you wish to link to the Subscription. - Example: MUxdJCr9xTMnmt1vGUAqV9z4 |
nickname |
string, optional | - A human-readable name for the resource. - Example: Finflix Gold Package |
start_subscription_at |
string (date-time), optional | - Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing. - Example: 2025-05-05T22:42:05.490Z |
subscription_details. notification_preferences. send_confirmation |
boolean, optional | - Whether to send a confirmation email to the user. - Example: true |
subscription_plan_id |
string, required | - The ID of the Subscription Plan from which to create the Subscription. - Example: subscription_plan_ctBbJ1ihsC8Hpju4RQfZE |
total_billing_intervals |
integer, optional | - The total number of billing intervals for the Subscription. - Example: 12 |
Uploading and Verifying Your File
- From the Import Subscriptions page, name your import file and upload the CSV file you filled out with your information.
- After uploading the file, click Verify File.
- A Subscription Import page displays with an "Uploading and Verifying File" banner indicating the file is being verified.
Viewing Import Status
You don’t need to wait for the import to complete. You can leave and return later to check the status from the Subscription Imports tab on the main Subscriptions page.
If Verification Fails
If file verification fails, the banner title changes to "File Verification Failed" with a link to Download the verification errors (CSV) and the option to Upload a Corrected File.
If Verification Succeeds
If file verification succeeds, the banner title changes to "File Verified" to show your subscriptions were successfully verified.
A Confirm Import popover appears with a message showing how many subscriptions will be imported and asks if you want to proceed.
Click Import Now to import all subscriptions in the file. The banner text updates to show the import is in progress.
When the import finishes, the banner text updates to show completion. It also provides an option to download CSV results.
Imported subscriptions now appear under Imported Subscriptions.
Viewing Your Imported Subscriptions
You can view the imported subscriptions from the main Subscriptions page › Subscription Imports tab.