Importing existing subscriptions is an upload of a file with data on your customers’ subscriptions. Based on the uploaded data, subscriptions are automatically created in the Rainex system without the need to manually transfer the data.
Please note that although the transfer of subscription data is automatic, your account must be properly prepared for these subscriptions to work correctly.
- Pre-set the currencies and frequencies used in your subscriptions.
- Create all the products you sell on your subscriptions.
- Create subscription plans with set prices.
- Create addons attached to your subscriptions and set prices for them as well. Charges data attached to subscriptions is not portable because they are one-time items, and not recurring ones like the subscription itself.
- Last but not least manually enter or import customer data. Note that if you accept automatic payments from customers, you must have the appropriate payment gateway connected and the payment method of each customer with an auto-payment added.
So, go to the import data tab in the settings section. Select import data and on the next page select import subscriptions.
Enter the name of the operation and download the document sample to fill in. As per the template, the document you will upload for import should be in CSV format.
The document consists of a series of mandatory and optional columns. Please follow the instructions to quickly and correctly complete this document for importing subscriptions.
Filling out the document #
id is the future unique identifier of the subscription, which should consist of digits and/or letters of the Latin alphabet of upper and/or lower case. This field is mandatory.
customer_id – the following field is also mandatory. When creating customers or importing their data, each customer is either automatically assigned an ID or you fill in the custom ID field. In this field, enter the IDs of customers whose subscriptions you import in the order of importing their subscriptions. You can find them in the billing section, in the customers tab, in the card of each client.
status – this column will display the status of imported subscriptions and is also mandatory.
A subscription can be imported in only one of three statuses:
- Active for valid subscriptions whose billing cycles have already started;
- InTrial for subscriptions that are in a trial period;
- and Future for scheduled subscriptions which are set to activate or start the trial period later than the import of this subscription.
Please note that the subscription statuses must be specified in the column in this InTrial, Active, Future format.
auto_collection – this column is optional and should be filled in only if autopayment is enabled in the imported subscription and a primary payment method is added for the customer in the Rainex system. If these conditions are met, write on in the column for the corresponding customers. For clients without autopayment write off in this column or just leave the column empty.
future_invoice_days_before_end_period – fill in this column to specify how many days before the end of the billing period the invoice should be issued to the customer. Enter an integer that is greater than 0, but not greater than or equal to the length of the billing period itself.
days_notify_about_unpaid_invoice – if you want payment reminders to be sent to the customer after a future invoice is issued and before the end of the billing period (of course, the reminders will not be sent once the invoice is paid), specify days. Specify the days as integers within the time period from the invoice issuance to the end of the billing period. That is, these numbers must be greater than 0 and less than the number in the future_invoice_days_before_end_period column. We ask you to observe the following format of writing “1, 2, 5”, including quotation marks (when generating csv file in Google tables, quotation marks are put automatically). Please note that for this function to work, you need to enable sending of corresponding emails in the notifications settings beforehand.
include_vat – be sure to specify in this column whether VAT is included in the price of this subscription or not. This information is necessary for further generation of invoices to the client. If VAT is included, write true in the subscription line in this column, and if excluded – false (TRUE and FALSE are also valid).
start_date – the data in this column is consistent with the data in the status column and is mandatory. So, if the subscription status is Active or InTrial, it is logical that at the moment of import it has already been started, which means that the column should contain a date earlier than the date of importing data about this subscription. Correspondingly, for a subscription in Future status, the date should be later than the date of the ongoing import.
Dates in this column should be written in the following format YYYYY-MM-DDT00:00:00:00+00:00 (T is time including milliseconds, if you don’t have creation time data, leave 0 everywhere as in this template). For example, 2023-09-14T09:20:242849+00:00.
activated_on – this column is required to be filled in only if the imported subscription is in the Active status. For InTrial and Future statuses, leave the fields empty.
Set the subscription activated on date for the customer using the same template as start_date. Enter YYYYY-MM-DDT00:00:00:00+00:00. If you do not have time data, leave 0 in this part of the string as in the example. Note that this date can be the same as start_date if the subscription was started immediately, or can be later than start_date if its activation was preceded by a trial period, but cannot be the same or later than the date of importing this subscription data, as otherwise it should be in a different status.
trial_ends_on – this column is mandatory only if the imported subscription is in InTrial status. For Active and Future statuses, leave the fields blank.
Any trial period must have an end date, when after the customer pays, the subscription will go to the Active status. Set an end date that is later than the data import date for this subscription (because otherwise it must be in active subscription status) using the same template as start_date. Enter YYYYY-MM-DDT00:00:00:00+00:00. If you don’t have time data, leave 0 in this part of the line as in the example.
total_billing_cycles – subscription by type of billing cycles is divided into 2 types: forever and fixed. Perpetual subscription will last as long as the customer continues to use your product, even for the next 50 years. Fixed subscription means that the number of billing cycles is limited and when they expire for the customer, the subscription on these terms will no longer be available for them.
If the subscription is fixed, enter in this column the number of billing cycles that were set at the time of creating this subscription for the customer. It is the original number at the time of creation, not how many are left!
If the subscription is forever, just leave its row in this column empty.
current_term_end – this column is required to be filled in only if the imported subscription is in Active status. Since you are importing already active subscriptions, they may be at different stages of the cycle. Therefore, for each active subscription, specify the end date of the current billing cycle, which will affect further invoicing of the customer. Set the date using the template YYYYY-MM-DDT00:00:00:00+00:00 (if you do not have time data, leave 0 in this part of the line as in the example). Note that this date must be later than the dates in the start_date and activated_on columns.
billing_cycles_left – be sure to fill in this column if you have specified in total_billing_cycles that the subscription is fixed and is in Active status.
This column does not apply to subscriptions in the InTrial and Future statuses, because the billing cycles countdown for them has not started yet, so it does not need to be filled in. If you have left the total_billing_cycles column empty, i.e. the subscription is perpetual, leave this column empty as well.
In this column you specify how many complete billing cycles of the subscription out of the total number of its billing cycles are still unexpired, i.e. without taking into account the current cycle. The number in this column must necessarily be less than the total_billing_cycles. For example, if the subscription at the moment of import is running its penultimate cycle and only 1 full billing cycle remains until the end of its validity, write the value 1 in the corresponding line.
future_trial_duration – when you specify that the imported subscription is in the Future status, it will be switched to the Active or InTrial status in the future when the date specified in the start_date column occurs. Fill in this column only if you provide the customer with a trial period for this future subscription (for immediate activation, leave the fields empty). So, enter an integer in this column that corresponds to the length of the trial period. You only enter the value here, and the measure in the next column.
future_trial_duration_units – and now enter here the value of day or month, which will correlate with the number from the previous column and form the duration of the trial period for the future subscription. This column becomes mandatory if you have filled in the future_trial_duration column.
General explanation for items/[index]/ columns.
A subscription can have multiple line-items, i.e. a rate and addons attached to it. Columns with a single index describe a single line-item. Thus the index is a variable that helps to identify whether the data belongs to a particular line-item.
The first four columns with a value of 0 in the index must always include data about the plan of the subscription being imported.
Importing addon data is accomplished by copying the four columns, changing the index in all four, and filling in the addon data. All further index values from 1 to infinity denote addons attached to the subscription. With each new item, the index number will increase by one.
For example, you have one subscription that has five addons attached to it, and the other subscriptions have either one addon or no addons at all. In this case, you fill columns with index 0 with the corresponding data for each subscription. Then you copy the four original columns, paste this entire set 5 times sequentially, also sequentially changing the indexes to integer values from 1 to 5 for the entire set of four columns. In this case, you fill in data about all five addons for the largest subscription, leaving these columns empty for other subscriptions for which there is no such data.
Please keep in mind that all subscription items must have the same duration and currency.
As we have said before, it is not possible to import data about attached charges, as they are not repetitive operations.
items/[index]/item_price_id – this column is mandatory and must include the price ID of the plan you created before the data import. To find the required data in the catalog section go to subscription plans and then to the appropriate plan for the imported subscription. In the plan card click on the price set for this subscription and on the price details page you will see the alphanumeric code of the ID, which should be specified in these fields of the data import document.
items/[index]/quantity – according to the pricing structure, rates and addons are divided into flat fee and per unit. This column is mandatory only for per unit items (for flat fee leave the field empty). Specify the number of items here as an integer.
items/[index]/free_quantity – this column is optional for per unit pricing. Set an integer value here if some of the items in the items/[index]/quantity column are free. Accordingly, the number in this column must be less than the number in the items/[index]/quantity column. For flat fee also leave the field empty.
items/[index]/unit_price – mandatory column where you specify the price of subscription or attached addon. Please keep in mind that for flat fee the specified price will be the full price of the item. However, if the price of the item is per unit, the final cost will be calculated by multiplying this amount by the quantity specified in the items/[index]/quantity column minus the value in the free_quantity column.
Please note that for further correct display, the data in this column must follow a specific format. In Rainex you can accept payments in 3 types of currencies – with two decimal places, with three decimal places or without decimal places. When entering data into the table for import, you need to omit commas and write all signs together as an integer.
Let’s give an example for each currency type using the number 10 as an example.
- For 2 decimal currencies such as dollar, euro, pound and so on, you will need to write 1000, i.e. include the value of cents in the writing.
- For 0 decimal currencies such as the yen or the South Korean won – 10, since there are no decimal point values for this type of currency.
- And for 3 decimal currencies, such as Kuwaiti dinar or Omani rial, the correct format is 10000.
General explanation for discounts/[index]/ columns.
These fields are optional and depend on whether there is a discount in the subscription. But if there is a discount, all the following 5 columns must be filled in to display the data correctly.
Please note that the index for discounts starts again from 0. Item indexes and discount indexes are not related, because to which particular item the discount is applied is specified directly in the columns.
You can apply more than one discount to a subscription. Just like for items/[index]/, to add another item, copy all the columns, change the indexes by 1 more and fill them with the necessary data.
discounts/[index]/duration_type – discounts can be one-time or perpetual, for example, for promotions. For subscriptions in Active status, the one-time discount will be applied either to the invoice that is generated when importing or to the invoice in the next billing cycle. For subscriptions in Future and InTrial status, the discount will be applied to the first invoice after the subscription is activated. Accordingly, the perpetual discount will be applied to the subscription or its element for the entire duration of the subscription. Specify OneTime or Forever in this column in this exact spelling format.
discounts/[index]/apply_on – in Rainex you can create discounts of two types: for all subscription items, i.e. the discount will be deducted from the total invoice amount, and for each single subscription item and will apply only to the specified item. Depending on the application of the discount, specify SpecificItemPrice or InvoiceAmount in this column. Please keep the spelling format in the document as in this example.
discounts/[index]/item_price_id – if you entered SpecificItemPrice in the previous column, here you must enter the price ID of the specific item to which the discount will be applied. Copy the price ID of the plan or addon and paste it into this column. If you have written InvoiceAmount in the discounts/[index]/apply_on column, leave the field in this column empty.
discounts/[index]/discount_type – and finally the last classification of discounts divides them into two categories: calculated from a percentage or is a fixed amount. Specify Percentage in this column if the price is discounted as a percentage. If it is more convenient for you, or if it is agreed upon with the customer in advance and so on, you can deduct some value of the amount from the price. In that case, enter the FixedAmount value in this column. Again, we ask that you follow the spelling format specified here in the import document.
discounts/[index]/value – the values in this column depend directly on the values in the previous column discounts/[index]/discount_type.
If you specified Percentage there, enter a value between 0 and 100 including fractional values.
If FixedAmount, enter here the amount of the discount in the appropriate currency. Since in Rainex you can accept payments in 3 types of currencies – with two decimal places, with three decimal places and without decimal places, when entering amounts in the table, omit commas and write all currency as an integer.
Let’s give an example for each type of currency using the number 10 as an example.
- For 2 decimal currencies such as dollar, euro, pound and so on, you will need to write 1000, i.e. include the value of cents in the writing.
- For 0 decimal currencies such as the yen or the South Korean won – 10, since there are no decimal point values for this type of currency.
- And for 3 decimal currencies, such as Kuwaiti dinar or Omani rial, the correct spelling looks like 10000.
payment/amount – this column is optional and can be filled in only for subscriptions in Active status.
When importing a subscription in the middle of the billing cycle, an invoice is automatically generated in the Rainex system. In this field you regulate whether this invoice will be immediately in the status of paid, because the customer has already made a payment for the current billing cycle or the customer has to pay it. In this column you specify the payment for the invoice. Here you can enter the full amount of the invoice for this subscription, then the invoice will be considered paid. You can enter an amount less than the full invoice amount for this subscription and then the invoice will be considered partially paid. Or you can enter an amount greater than the full invoice for the subscription, and then a credit note will be generated and an adjustment will be made to the customer’s balance on the next invoice issuing. If you leave this field blank, a payable invoice will be generated.
Please note that for further correct display, the data in this column must follow a specific format. In Rainex you can accept payments in 3 types of currencies – with two decimal places, with three decimal places or without decimal places. When entering data into the table for import, you need to omit commas and write all signs together as an integer.
Let’s give an example for each currency type using the number 10 as an example.
- For 2 decimal currencies such as dollar, euro, pound and so on, you will need to write 1000, i.e. include the value of cents in the writing.
- For 0 decimal currencies such as the yen or the South Korean won – 10, since there are no decimal point values for this type of currency.
- And for 3 decimal currencies, such as Kuwaiti dinar or Omani rial, the correct format is 10000.
Importing the document #
When the document is completed, upload it to the system on the Subscription Import page. At this stage, the initial validation of the data is carried out and if you have filled in the data incorrectly, the system will notify you immediately. If everything is in order, you will be taken to the second step of data import.
Step number two is column mapping. That is, the system checks and correlates the data from the document (CSV headers column) with the data requirements.
If there is a data mismatch, you will see the unmatched status for the corresponding columns. In this case it is necessary to edit the mapping, i.e. direct the data to the appropriate section for further correct work.
Click Edit Columns and in edit mode click the edit icon in the row whose value you want to change. In the Matched headers column, select from the drop-down list the value you would like to replace the automatically pulled one with that is more appropriate to the column content of your CSV document. Please note that if the header includes an index, this will also need to be replaced if necessary by simply clicking on the text box and typing in the desired value. Be sure to click save in the edit bar so that your changes are not lost.
Also in edit mode you can see the Skip button, which you can click if you want the column to be ignored when importing. You can also use Skip when interchanging columns so that the system does not show an error, as it is not possible to use the same value for two columns at the same time.
When you have finished editing and made sure that the changes in each row you edited have been saved, click Finish edit. Confirm the operation in the pop-up window that appears and the import process is started.
In the operation card, you can see both the overall status of the operation and the upload status of each entity being uploaded. Don’t be afraid to exit the card and start other operations in Rainex, the data is saved in the system and will not be lost when you switch to another page. The import may take some time depending on the amount of data being imported. Subscription data will be displayed under the subscriptions tab in the billing section as it is loaded.
When the import is complete, data about the operation can be found in the Operations History tab.
