Table of Contents
- A Quick Overview Of User Importation
- Having Trouble w/ CSV Import Structure?
- CSV Import (and/or Mass-Update) Examples
- Password Value In Your CSV Import (and/or Mass-Update) File
- Importation is Always Performed Silently
- Additional Information Can Also Be Included
- Optional Paid Subscr. Gateway Value
- Optional Paid Subscr. ID Value
- Optional First Payment Date (or Dates)
- Understanding Custom Registration/Profile Fields
s2Member comes with two different Import/Export Tool flavors. Both flavors import/export in the CSV (comma-separated values) format. However, they each construct CSV data differently.
Advanced Import/Export Tools allow for a much larger set of data to be manipulated. In this article I will discuss the Simple Import/Export Tools. If you would like to learn more about the Advanced Import/Export Tools please click here.
A Quick Overview Of User Importation
A popular s2Member Pro feature is the ability to import and/or mass-update users in WordPress. Import files (and/or mass-update files) can be uploaded in CSV file format. Or, you can copy/paste data into a form field provided by s2Member Pro.
Having Trouble w/ CSV Import Structure?
If you have any trouble, please perform an export first. s2Member’s export files are already formatted for easy reimportation. In other words, you can use them as a guideline for building your own import files. All data fields are properly encapsulated by double-quotes and separated by commas. You’ll also need to make sure that all of your data fields are in the proper order.
CSV Import (and/or Mass-Update) Examples
The format is always the same. You’re constructing what is known as a CSV file (Comma-Separated Values). s2Member Pro has some minimum requirements when importing and/or mass updating users, so I will touch on those first. Please see the following examples. One user per line please. Each line of your CSV import file must contain these values, at a minimum.
"ID","Username","Password","First Name","Last Name","Display Name","Email"
The difference between importing a new user and updating an existing User, is the presence of the ID value in each line. If you want to update an existing user, please set the ID value to the User ID in WordPress matching the account you want to update. If you want to import a new user, please set the ID value to an empty string.
Example New User Import Line In A CSV File
Example mass-update Line In A CSV File (Includes an ID Value)
johndoe22 is User ID 123 in WordPress.
Mass-updates are easy to deal with, because s2Member Pro also provides a user export tool, which provides you with a CSV export file with all of your users. s2Member’s CSV export file is 100% compatible with the s2Member Pro import functionality (which is nice). In other words, all of the User IDs (and some other data) from WordPress will already be included in your export file. You make changes to this data and then import the CSV file to mass-update user accounts at any time.
Password Value In Your CSV Import (and/or Mass-Update) File
If you fill the Password field, the Password that you specify (in plain text) will be used. Otherwise, a Password will be auto-generated by s2Member. The Password field can also be used with an ID update, to update/change the current Password for a certain user—so long as the ID field is also filled in, and it matches an account already in the system. Or, if you fill the ID field to update an existing account and the leave the Password field empty, the existing Password for the account matching the ID you specify will remain unchanged.
Importation is Always Performed Silently
Users will not be contacted by s2Member. Not unless you have another plugin installed that conflicts with s2Member’s ability to perform the import properly. You should always test one or two accounts before importing a large number of users all at once.
If you want users to be contacted you can add them manually by going to WordPress Dashboard → Users → Add New and selecting one of the s2Member Roles from the drop-down menu.
Additional Information Can Also Be Included
Here is the full list of all possible import (and/or mass-update) values that can be included during importation.
"ID","Username","Password","First Name","Last Name","Display Name","Email","Website","Level[0-9]+ or Role ID","Custom Capabilities","Registration Date (mm/dd/yyyy)","First Payment Date (mm/dd/yyyy)","Last Payment Date (mm/dd/yyyy)","Auto-EOT Date (mm/dd/yyyy)","Custom Value (starts w/domain)","Paid Subscr. ID","Paid Subscr. Gateway","Custom Registration/Profile Field Value","another Custom Registration/Profile Field Value", ... and so on, for as many Custom Registration/Profile Fields that you'd like import.
Here is a full example with all fields filled in; plus two Custom Registration/Profile Field values.
Optional Paid Subscr. Gateway Value
If you supply a Paid Subscr. Gateway, you must use one of these values please:
stripe; for Stripe and/or Bitcoin
paypal; for PayPal Standard or PayPal Pro
alipay; for AliPay
authnet; for Authorize.Net
ccbill; for ccBill
clickbank; for ClickBank
Optional Paid Subscr. ID Value
If you supply a Paid Subscr. ID, please obtain this information from your payment gateway. If the customer paid you one time for access, your payment gateway should provide you with a Transaction ID. If the customer is paying you on a recurring basis (or on a set schedule of some kind), your payment gateway should provide you with a Subscription ID. Please do not attempt to use a specific Transaction ID if you also have a Subscription ID. Use the Subscription ID if you have one—this is preferred by s2Member.
Some payment gateways might use different terms for these values. For instance, ClickBank uses a Receipt Number instead of a Transaction ID. Google Checkout (when integrated with s2Member Pro) will be passed a unique TID/SID value. If you’ve integrated with Google Checkout please use the TID/SID value, always with an
s2- prefix. This value can be obtained from inside your Google Checkout account in the Transaction Description field. s2Member defines this value, not Google. Please use s2Member’s value if at all possible.
The rule is, IF there is a Subscription ID (or something similar), please use that first. If there is only a Transaction ID (or something similar), use that instead of a Subscription ID. For some transactions (e.g., “Buy Now” transactions) there will only be a Transaction ID value. That’s fine.
Optional First Payment Date (or Dates)
You have two options available. You can either supply a simple date in this format:
mm/dd/yyyy, or you can import an array of First Payment Dates, in the form of Unix Timestamps. s2Member has the ability to record and monitor First Payment Dates at each specific Membership Level. The array it expects consists of the following:
array( 'level' => '[timestamp of first payment date, regardless of level]', 'level1' => '[timestamp of first payment date at level #1]', 'level2' => '[timestamp of first payment date at level #2]', 'level3' => '[timestamp of first payment date at level #3]', 'level4' => '[timestamp of first payment date at level #4]' )
If you decide to import an array with some of these timestamps, you will need to use PHP’s serialize() function to convert the array into a string representation. If you have any trouble, please perform an export first. s2Member’s export files are already formatted for easy reimportation. In other words, you can use them as a guideline for building your own import files. By default, s2Member exports an array of timestamps.
Understanding Custom Registration/Profile Fields
The end of each line in a CSV import file can include Custom Registration/Profile Field values (optional of course). The excerpt below is taken from the full example above with extended details. You can see here that s2Member Pro expects the following format with respect to Custom Registration/Profile Field values.
...,"Custom Registration/Profile Field Value","another Custom Registration/Profile Field Value", ... and so on, for as many Custom Registration/Profile Fields that you'd like import.
Custom Registration/Profile Fields can be configured in your Dashboard with s2Member. Each Custom Registration/Profile Field that you create will be associated with a unique ID that you assign it. This is how s2Member knows which Registration/Profile Field you’re referring to whenever you perform an importation and/or mass-update.
You can only import Custom Registration/Profile Fields that have been previously defined in your Dashboard with s2Member. If you attempt to import Custom Registration/Profile Fields that have not already been defined by your installation of s2Member they will simply be ignored (i.e., skipped over). Define Custom Registration/Profile Fields first please.
See: WordPress Dashboard → s2Member → General Options → Registration/Profile Fields
Your Custom Registration/Profile Field values should be listed in alphabetical order, based on your Custom Registration/Profile Field IDs (i.e., values listed in the order of your alphabetized Custom Registration/Profile IDs). This is based on the Custom Registration/Profile Field IDs you’ve configured with s2Member. See: WordPress Dashboard → s2Member → General Options → Registration/Profile Fields
A Quick Example To Demonstrate How This Works
If I have three Custom Registration Profile Fields. One with a unique ID
interests, and another with a unique ID
t_shirt_size, and another with unique ID
zipcode; this is how I would construct my CSV data for these fields (see the following example).
interests column value comes first, followed by the next (in alphabetical order)
t_shirt_size and then
zipcode. In the following example with values filled in, the Custom Registration/Profile Field with ID
interests is set to a value of
fishing,biking,computers. The value of
t_shirt_size is set to
xx-large. The value of
zipcode is set to
If you have any trouble understanding this, please do a full export of all users with s2Member Pro and then inspect s2Member’s CSV export file using a text editor (you can open CSV files in a text editor also). s2Member’s CSV export file is perfectly formatted for reimportation. If you have Custom Registration/Profile Fields configured, s2Member will format those in your export file (just as it expects to receive them during importation). In other words, you can use s2Member’s export file as a guideline when building your own CSV import file.
Custom Registration/Profile Fields With Multiple Values (Arrays)
If you have a Custom Registration/Profile Field that contains an array of multiple values (maybe from a select menu, or a set of checkbox values—where you allowed multiple selections to be made); you can import the array using PHP’s serialize() function. This allows you to convert the array into a string representation. s2Member will automatically unserialize() the value during importation. See the following example for a Custom Registration/Profile Field with ID: