Import Subscriptions
Give has a built-in ability to import subscriptions from a CSV file. This document will walk you through how to do that.
Preparing the CSV
The Import Subscriptions tool accepts CSV files, and it must be formatted correctly for the import to succeed. You can download a sample file from the import tool to ensure your file has the correct format.
Required Fields
We recommend filling out all columns for the most accurate results, but these fields must be filled at minimum:
- form_id
- donor_id (if they’re an existing donor)
- period
- frequency
- amount
- status (active, expired, cancelled, suspended, paused, pending)
Data Formatting
Ensure each column’s values are in the correct format.
| Field | Acceptable Value Formats |
|---|---|
| form_id | number |
| donor_id | number or empty |
| first_name | text |
| last_name | text or empty |
| valid email address | |
| period | day, week, quarter, month, year |
| frequency | number |
| installments | number (0 = ongoing) |
| amount | dollar amount with decimals (if currency supports it) |
| fee_amount_recovered | dollar amount with decimals (if currency supports it) |
| status | active, expired, cancelled, suspended, paused, pending |
| mode | live, test |
| transaction_id | text (unique transaction ID provided by your payment gateway) |
| gateway_id | text (unique ID Give assigns each payment gateway: stripe, stripe_payment_element, paypal-commerce, etc.) |
| gateway_subscription_id | text (unique subscription ID provided by your payment gateway) |
| created_at | datetime (ex: 2024-01-10 12:30:00) |
| renews_at | datetime (ex: 2024-01-10 12:30:00) |
| currency | valid currency code (3-letter uppercase currency code like USD, EUR) |
Note: If the Gateway Subscription IDs are not present or incorrect, your subscriptions will not be able to sync with the gateway.
Importing Subscriptions
The Import Subscriptions tool allows you to import subscriptions from any platform into Give. It works by allowing you to map the columns of your CSV file to any Give field, so you can import as much or as little information as you like.
Uploading your CSV file
Ensure your CSV file is formatted correctly, includes the required columns, and uses either comma or tab delimiters before you begin.
- In your website admin, navigate to Give > Tools > Import.
- Find the Import Subscriptions option, and use the Import Subscriptions button to get started.
- Choose your CSV file and upload it to your site.
- Select the delimiter used by your CSV file (Comma or Tab).
- Choose whether the subscriptions being imported should be marked as Test.
- Decide whether to create new WordPress users for any new donors included in your import.
- Decide whether to delete the CSV after import (enabled by default).
- Specify a number of rows per cycle for batch processing (helpful for large files).
- Select Dry Run if you’d like to preview the results of your import without making changes.
- Use the Begin Import button to start processing.
Note: This process requires uploading your CSV to the Media Library for import. The file will be accessible via the web for anyone who knows the URL. It’s important to select the Delete CSV after import option if you do not wish this information to be available to the public.
Mapping Columns to Fields
After the CSV is uploaded, Give attempts to match the column headings to related fields within Give. It’s critical that you check that field mapping meets the following criteria:
- The required fields are each mapped to a column.
- None of those fields are being mapped from two different columns.
- None of those columns on the CSV contain empty rows.
The import will fail or only partially complete if any of these criteria are not met.
What happens behind the scenes here when you click to import: The tool pulls the data into the WordPress database, and any conflict resulting from it trying to pull two things into the same field metadata will result in the tool skipping that donation.
Completing the Import
After you select Begin Import, your import will start to process. Process time depends on how many subscriptions you are importing. On most hosting configurations, it happens quickly. If the process fails at this point, go back to the Upload step and select a smaller number of donations to process in each batch.
Once your import is done processing, you will see a message telling you it is complete. You will see how many rows were processed and how many subscriptions were created so you can confirm the results.
If you need to manually add a subscription that was not imported, check out the article for adding existing subscriptions to Give using Manual Donations.
FAQ
1. The file you’re importing is a CSV file.
2. Your CSV includes the required columns, the columns are named correctly, and each column has values.
3. The values in your CSV file are formatted correctly.
4. You checked that the field mapping step meets the 3 criteria for a successful import.
If all else fails, contact our support team for assistance. They’re always happy to help.
That means that if the donor_id matches, but the email doesn’t, the subscription will still be assigned to the donor. If the email matches, but the donor_id doesn’t, the subscription will be assigned to the donor that matches the donor_id, or a new one will be created.
