Membership Imports

You can import Memberships into Spektrix using the Importer. This can be useful if you process Memberships outside of Spektrix for reasons such as upholding historic direct debit arrangements. 

Importing Memberships using the Importer saves you time because you don’t have to individually process each customer’s payment for your Memberships to be uploaded into Spektrix.

The concepts in this article require a basic understanding of imports and Memberships. Before reading this article, make sure you’re familiar with:

• Introduction to doing your own imports
• Introduction to Memberships 

TIP: To start importing Memberships, you'll need to request access to the Importer tool. To learn more about getting started with imports, read Introduction to doing your own imports.

How does importing Memberships work?

You can import Memberships into Spektrix using a transaction import. This means that each record you upload will generate an Order within Spektrix which contains the details of each Membership purchase against a Customer Record.

TIP: You can create new Membership types using the import. Alternatively, you may wish to set up any new Memberships before making your import.

To import Memberships into Spektrix, you will need to compile the data about each Membership Order into a CSV file. You’ll then upload the CSV using the importer to add the data into your system.

The CSV file you upload must be formatted exactly in line with the guidance in this article. 

Before uploading your import, you’ll need to check your data. If your data does not match the required format, this can result in incorrect data being uploaded into your system.

WARNING:  You are responsible for the data you import and for fixing any mistakes. Spektrix can’t reverse any imports you upload.

Once you’ve prepared your CSV file, you can upload it into Spektrix to validate it and then import it using the Importer.

Successfully imported data will be made available alongside your other data in the Sales and Opportunities interfaces, and in Reports and Customer Lists.

After uploading your import, you should spot-check your uploaded data to ensure that the data has been imported as you expect. 

How to import Memberships

Work through the following steps in order to import Membership payments into Spektrix.

1. Prepare your CSV file
2. Validate your data
3. Import your data
4. Check your data

1. Prepare your CSV file

Transform your data into the correct format before you upload your import. Use a CSV editor program such as Excel or a third-party tool like Rons Data Edit (if approved by your IT team). Make sure that the CSV editor program you are using can save files in the UTF-8 format.

If you're using a formatted report from Spektrix as the basis of your CSV file, you must still check the data and ensure it’s in the correct format for the import.

REMINDER: Your CSV File must be formatted exactly as outlined in this article to import successfully.

Your CSV file

For an import to be successful, your CSV file must meet the following standards:

• All required fields must be populated with data. Read the Required Data Fields section of this article for details about each of the required fields for a Membership import.
   
• Each column name must match the correct column name exactly, including capitalisation and spaces. Read the Required Data Fields section of this article for details about each of the column names.
   
• Data must match the required format for the field type. For example, you cannot import free text into a Yes/No field. For more information, read the Field Types section of the Introduction to the Importer.
   
• Each CSV must be in the UTF-8 encoding format. Read more about UTF-8 encoding in the Introduction to the Importer.

Required Data Fields

In the table below, we’ve outlined the different data fields that can be included in Membership imports and whether they are required.

If a field that isn’t required is left blank, then no data will be imported into this field.

Renewals

For a Membership to be a renewal, the customer must have a Membership of the same type which is in its renewal or grace period. 

When importing Memberships, ForceRenewal or RenewalOnly can be used separately or in conjunction to indicate if the imported Membership should be a renewal. 

• ForceRenewal

If this column is set to Y, and the customer has an existing Membership of the same type in its renewal or grace period, then the imported Membership will be processed as a renewal.

If necessary, ForceRenewal will override and set the Start Date to the date after the previous Membership expires, as long as this is still before the specified End Date. 

If there is not an existing Membership that matches, then the imported Membership will be processed as new and not a renewal.

• RenewalOnly

If you enter Y in the RenewalOnly column, then the Membership will only be imported if it’s possible to process the Membership as a renewal. If this is not possible, then the record will fail and won’t be imported.

If you try to import a Membership as a renewal using only the RenewalOnly column, the StartDate of the import must be the date after the previous Membership has ended. Otherwise, the record will fail and won’t be imported.

As ForceRenewal adjusts Membership dates to ensure that all possible Memberships will be renewed, using this in conjunction with RenewalOnly will decrease the number of Membership records that will fail to import. 

Scenario: Importing Membership with start date 10 Feb 2026

To demonstrate how importing renewals works, we’ve outlined how the import will work for each of the four ways you can process a renewal below.

• There are four ways you can process a renewal which depend on the combination of values in the ForceRenewal and RenewOnly fields:

  • ForceRenewal N, RenewOnly N (if you choose not to include these columns, then this is how your Memberships will be imported)
  • ForceRenewal Y, RenewOnly N
  • ForceRenewal N, RenewOnly Y
  • ForceRenewal Y, RenewOnly Y 

  The way your renewal is processed also depends on the status of the Membership on the Customer Record you are importing against. 
  
  Processing renewals depends on whether the Customer Record has:

  • No Membership of the same type
  • A Membership which is not within the Renewal or Grace Period at the time of the import
  • A Membership which is within the Renewal or Grace Period at the time of the import
  • A Membership which has expired the previous day to the new Membership start date and is in its Renewal or Grace Period at the time of the import

  In each scenario, we’re importing a Membership with a start date of 10 February 2026.
  
  Click through the tabs below to see the result of each different scenario.
  
   

  • ForceRenewal =N RenewOnly =N
    
     

    Start Date	2026-02-10
    ForceRenewal	N
    RenewOnly	N

    
     

    • If there is no Membership of the same type on the Customer Record, then the Membership will import as new with start date 10 February 2026, not as a renewal.
      
       
    • If there is a current Membership of the same type on the Customer Record, with an expiry date of 5 February 2026 which is not within the Renewal or Grace Period at the time of the import, then the Membership will import as a new Membership with a start date of 10 February 2026, not as a renewal. 
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry date of 5 February 2026 which is within the Renewal or Grace Period at the time of the import, then the Membership will import with start date 10 February 2026, not as a renewal.
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry of 9 February 2026 and the Membership is in the Renewal or Grace period at the time of the import, then the Membership will import with start date of 10 February 2026, as a renewal 

  • ForceRenewal = Y RenewOnly = N

    Start Date	2026-02-10
    ForceRenewal	Y
    RenewOnly	N

    • If there is no Membership of the same type on the Customer Record, then the Membership will import as a new Membership with a start date 10 Feb 2026, not as a renewal.
       
    • If there is a current Membership of the same type on the Customer Record, with an expiry date of 5 February 2026 which is not within the Renewal or Grace period at the time of the import, then the Membership will import with a start date of 10 February 2026, not as a renewal.
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry date of 5 February 2026 which is within the Renewal or Grace Period at the time of the import, then the Membership will import with a start date of 6 February 2026, as a renewal. Note that this changes the start date than what is found in the import file.
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry date of 9 February 2026 and the Membership is in the Renewal or Grace period at the time of the import, then the Membership will import with a start date of 10 February 2026, as a renewal.

  • ForceRenewal = N RenewOnly = Y

    Start Date	2026-02-10
    ForceRenewal	N
    RenewOnly	Y

    • If there is no Membership of the same type on the Customer Record then the record will fail and the Membership will not be imported.
    • If there is a current Membership of the same type on the Customer Record, with an expiry date of 5 February 2026 which is not within the Renewal or Grace period at the time of the import, then the record will fail and the Membership will not be imported.
    • If there is a Membership of the same type on the Customer Record with an expiry date of 5 February 2026 which is within the Renewal or Grace Period at the time of the import, then the record will fail and the Membership will not be imported.
    • If there is a Membership of the same type on the Customer Record with an expiry date of 9 February 2026 and the Membership is in the Renewal or Grace period, then the Membership will import with a start date of 10 February 2026, as a renewal.

  • ForceRenewal = Y RenewOnly = Y

    Start Date	2026-02-10
    ForceRenewal	Y
    RenewOnly	Y

    • If there is no Membership of the same type on the Customer Record then the record will fail and the Membership will not be imported.
      
       
    • If there is a current Membership of the same type on the Customer Record, with an expiry date of 5 February 2026 which is not within the Renewal or Grace period at the time of the import, then the record will fail and the Membership will not be imported.
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry date of 5 February 2026 which is within the Renewal or Grace Period at the time of the import, then Membership will import with a start date of 6 February 2026, as a renewal.
      
       
    • If there is a Membership of the same type on the Customer Record with an expiry date of 9 February 2026 and the Membership is in the Renewal or Grace period at the time of the import, then the Membership will import with a start date of 10 February 2026, as a renewal.

Memberships with a Donation

You can specify the portion of the Membership price which should be accounted for as a benefit (also known as goods and services) or Donation.

When importing transactions into existing Memberships which contain a Donation portion, there are two column names you’ll need to populate:

1. Price: Enter the price of the Membership without the Donation portion included.
2. RelatedDonationAmount: Enter the Donation portion of the Membership price. 

For example, if you have a $30 Membership, with $10 benefit and a $20 Donation you would enter:

100% Donation Membership

For Memberships that are 100% Donation (and no benefit), you will need to enter 0 into the Price column.

For example, if your Membership is $50 and that is all Donation, you would enter:

Creating new Memberships

If importing Memberships where there is no existing Membership of the same name, then a new Membership will be created. 

Using the Importer, you can only create new Memberships which don’t contain a Donation portion. To import Memberships that contain a Donation portion, you must ensure that the Membership already exists in your system. 

Gift Aid

For organisations in the UK, you can indicate whether the Donation portion of a Membership you are importing is Gift Aid claimable, and whether the Gift Aid has already been claimed. 

Gift Aid can only be claimed on the Donation portion of a Membership, therefore RelatedDonationAmount must have a value above 0 for it to be possible to mark the payment as Gift Aid Claimable.

REMINDER: Gift Aid is only claimable where there is a valid Gift Aid Declaration.

• RelatedDonationGiftAidClaimable

As a default, imported Memberships are opted out of Gift Aid. This means that if you leave the column blank, enter N or don’t include the column then the Memberships you import won’t be eligible for Gift Aid claims.

If you enter Y in the RelatedDonationGiftAidClaimable column, then the Membership becomes eligible for Gift Aid claims.

WARNING: Keeping an accurate record of Gift Aid is important to avoid claiming Gift Aid on a Membership twice. If you mark a Membership as Gift Aid Claimable then it is not possible to remove this from future Gift Aid claim reports without returning and repurchasing the Membership.

• RelatedDonationGiftAidClaimed

This field can only be set if RelatedDonationGiftAidClaimable is set to Y.

If RelatedDonationGiftAidClaimable is set as N or not included, the Membership will not be Gift Aid claimable, and the RelatedDonationGiftAidClaimed field cannot contain a value.

If you enter N in the RelatedDonationGiftAidClaimed column, then the Donation portion of the Membership you are importing will be included in future Gift Aid claims.

If you enter Y in the RelatedDonationGiftAidClaimed column, then the Donation portion of the Membership you are importing won’t be included in future Gift Aid claims. 

If you enter Y in the RelatedDonationGiftAidClaimed column, then in Spektrix, a claim will appear to have been generated and successfully processed. This will not submit your claim to HMRC. A record will be created for every line in the import file. You can view these “claimed” records under the Admin Interface > Other > Gift Aid Claims. 

WARNING: By entering Y in the RelatedDonationGiftAidCalimed column, you are indicating that your gift aid has been processed and claimed outside of Spektrix. In Spektrix, it will appear as though your Gift Aid has been claimed through Spektrix.

Custom Fields

The Order Custom Field column can be used to import custom Order Attributes.

To add a custom field, use the OrderCustomField:{CustomFieldName} column name.

In the column name, replace {CustomFieldName} with the exact name of your Order Attribute.

REMINDER: Attribute names are case sensitive and must match exactly (including spaces) to be successfully imported. You'll also need to remove the curly brackets. Do not add a space between the colon and the start of your Attribute name.

For example, if your Order Attribute is "Is Direct Debit” then your column header would be:

OrderCustomField:Is Direct Debit

If your custom Order Attribute is a dropdown list, then the data in the column must match the dropdown values exactly.

 For example:

WARNING: If you have Order Attributes set up on your system which are marked as required, you will need to import these alongside your data. Your import will fail if you do not supply values for required Attributes.

Example

Click the image below to see a detailed example of a Membership Import. This example has been formatted correctly with all the required headings and is ready to be uploaded.

REMINDER: Don’t forget to save your CSV in the UTF-8 encoding format.

2. Validate your data

The Importer is found in the Settings interface.

TIP: To access the Settings Interface, you’ll need the Settings Administrator Role. If you don’t have this Role, ask the Settings Administrator in your organisation to add this Role to your User Account.

Each import type has two processes that can be run against it: Validate and Import.

All imports must be validated before they are imported. 

The validation process checks the data in the input file against validation rules to identify any issues in the CSV file. It does not check against data already in Spektrix (for example, customer data), so you may still get data-specific errors when running your import.

WARNING: Do not run your import until you have received a successful validation CSV.

How to use the Validator

1. Select the Import Type: Memberships:  
   
   
2. Click Validate:
   
   
    
3. Upload your CSV and click Run Validator:
   

REMINDER: CSV files must be in the UTF-8 format and contain all of the required information for your import.  

Once you’ve clicked Run Validator, you’ll see a Job Submitted icon in the top left of the screen:

Hover your mouse over the green check mark and click to download the CSV file to see the results:

How to read the validation document

The validator will give one of two types of responses:

• No validation error found 

If the validation is successful, the CSV will contain a message which reads: Validation completed successfully.

• Validation error found 

If the validation is unsuccessful, the CSV will contain a message explaining the failure. 

For example: Error processing record 23 Subscription to renew is outside the renewal or grace period.

In this example, the validation failed due to the subscription being outside of the renewal or grace period when the RenewalOnly column is Y and the ForceRenewal column is N. If you try to import a Membership as a renewal using only the RenewalOnly column, the StartDate of the import must be the date after the previous Membership has ended. Otherwise, the record will fail and won’t be imported.

Another example of a failed validation error message is:

VALIDATION FAILED WITH CsvDataException
Error processing row 1. Invalid date. Dates must be in the format yyyy-MM-dd. '20/03/2025' is not valid.

In this second example, the validation failed due to an incorrect date format. 

How to avoid common errors

Below we’ve listed some tips that can help you avoid common errors:

• Always check your data. If possible, we recommend working with another member of your team to perform the check.
   
• If you use Excel to edit your CSV files, you’ll need to set the date format to yyyy-mm-dd every time you open the file. Even if you save the file with the correct date format, when you open the file you’ll need to update the date format again.
   
• Remember to save your file in the csv UTF-8 format.
   
• If you need to re-import some rows of your data because they have failed, take out the successfully imported Memberships from your file.
   
• If you’re using Excel to create your import file,  errors will refer to the number of the error. This will not correspond directly with the row number in Excel. For example, “Error processing record 24” may refer to Row 25 of your Excel file.

3. Import your data

If your CSV file passes validation, then you can continue to import the file.  

REMINDER: A successful validation of your CSV file does not always lead to a successful import of your data.

How to run an Import

1. Select the Import Type: Memberships

   

2. Click Import:

    
    

3. Complete the Import CSV details:
   
   • Foreign Id Customer Custom Field Name: Leave blank
   • Foreign Id Order Custom Field Name: Leave blank
   • Upload the CSV file: Click select file and browse to the location on your computer where the CSV file is saved

After clicking Run Importer, you’ll see a pop up asking you to confirm the number of rows in the import file:

Click Confirm to continue with the import, or click Cancel to go back.

Once you’ve clicked Confirm, you’ll see a Job Submitted icon in the top left of the screen:

Hover your mouse over the green check mark and click on the link to the CSV file to download and see the results:

You’ll also receive an email notification to let you know the import is complete. This will be sent to the email address registered to your User Account. 

WARNING: Download and review the import results file before attempting to re-upload an import.

Import results file

A CSV report will be generated and available to download with the result of your import.

If the import is successful, you will see Import completed successfully:

If the import fails, you’ll see a message with an error reason. 

For example: Error processing record 1 No existing subscription that can be renewed.

The CSV report will contain a row for each record that had an error. 

Each row explains:

• On what record the error occurred
• The details of the error
• The contents of the object that caused the error (in a single cell, with line breaks between properties)

This file only lists errors. Any rows not listed will have been imported successfully. 

Depending on the error in the import results, you may want to amend the data and re-attempt to import for those specific rows. If you are re-attempting an import, remove any successfully imported Memberships from your file.

REMINDER: Successfully imported Memberships will fail if you attempt to import them again.

4. Check your data

Once you’ve completed your import, we recommend spot-checking your imported Memberships to ensure the data is being returned as you expected.

This is an example of how an Imported Membership might look in the Sales Interface:

Choose a few of the Memberships you have imported and check that the following information is accurate:

• The Membership name
• Price
• Dates: transaction, start, expiry

If your Memberships contain a Donation portion, you should also check that this information has been imported correctly. To do this, run the Donations Report with a custom Criteria Set of Transaction Date: today.

Troubleshooting Membership Import Errors

Below we’ve listed some of the common errors which can occur when importing Memberships and how to troubleshoot them.

• Invalid date. Dates must be in the format yyyy-MM-dd. '20/03/2025' is not valid.

Reupload the import with the correct date format. If you use Excel to edit your CSV files, you’ll need to set the date format to yyyy-mm-dd every time you open the file.

• Subscription to renew is outside the renewal or grace period.

Check whether the customer's existing membership is within the renewal or grace period at the time of import. 

If RenewalOnly is set to Y and ForceRenewal is N, the start date must be the day after the previous membership expired. Otherwise, the record will fail.

Consider using ForceRenewal = Y alongside RenewalOnly = Y instead as this will automatically adjust the start dates of the memberships to the day after each customer’s current/previous Membership.

If the grace period is too short for the transaction dates in the file, temporarily edit the grace period of each Membership by editing it in the Admin Interface. For example, from 62 to 365 days. You can edit the grace period before running the import, then reset it afterwards.

• No existing subscription that can be renewed.
  This occurs when RenewalOnly = Y but the customer has no current membership of the same type.

If some records should be new purchases rather than renewals, set RenewalOnly to N for those rows.

Double-check the MembershipName matches exactly - if the Membership name does not match the importer won't find an existing subscription.

• New subscription would have to start on or after it is set to expire.

This happens when ForceRenewal = Y and the adjusted start date (day after the existing membership's expiry) falls on or after the new membership's ExpiryDate.

Extend the ExpiryDate in the CSV so there's a valid membership period after the adjusted start date.

Review the existing membership's expiry date on the customer record to understand what start date the importer would calculate.

• Payment Type cannot be inactive: Imported payment

Go to the Admin Interface and check whether the Imported payment payment type is active. If it's been deactivated, reactivate it before running the import.