latest stable versions: v140614 (changelog)

Import (or Mass Update) Users

A Quick Overview Of s2Member® Pro User Importation

A popular feature provided by s2Member® Pro, is the ability to import and/or mass update Users in your WordPress® installation. 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.

In either case, you MUST follow the examples given below for everything to work properly. Please double-check your data before clicking the Import button. Please make sure that 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, based on the examples given below.

See: Dashboard -› s2Member® -› Import/Export -› User/Member Importation
After importing (and/or mass updating) Users/Members, you can inspect your work by going to: WordPress® -› Users. This is where all User data can be viewed/edited from the Dashboard. So look for new Users/Members that you imported to appear in the list here.

Having Trouble Structuring Your CSV Import File?

Do not fear. If you have any trouble, please perform an export first using s2Member® Pro. s2Member’s export files are already formatted for easy re-importation. In other words, you can use them as a guideline for building your own import files.

CSV Import (and/or Mass Update) File — Minimum Requirements

However you choose to import Users/Members, 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/Members, so I will touch on those first. Please see the following examples.

One User/Member 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
"","johndoe22","8834ks9903","John","Doe","John Doe","johndoe22@example.com"
Example Mass Update Line In A CSV File (Includes an ID Value)
"123","johndoe22","8834ks9903","John","Doe","John Doe","johndoe22@example.com"

Where User 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/Members. 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 User export file provided by s2Member® Pro. You make changes to this data, and then import the CSV file to mass update existing Users.

Regarding the `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. 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 (and/or Mass Updates) Are Always Done Silently

Users/Members will NOT be contacted by s2Member®. That is, 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/Members to be contacted, you can add them manually, by going to WordPress® -> Users -> Add New, and selecting one of the s2Member® Roles from the drop-down menu.

Additional Information Can Also Be Included During An Importation

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.

"","johnsmith22","mY!passwrD","John","Smith","John Smith","john.smith@example.com","http://www.example.com/","2","music,videos","12/31/2000","01/10/2001","12/31/2020","12/31/2021","www.example.com|123.357.125.654","I-2342934SSER243","paypal","fishing,biking,computers","xx-large"

Regarding the Optional `Paid Subscr. Gateway` Value

If you supply a Paid Subscr. Gateway, you must use one of these values please.
Use: paypal, alipay, authnet, ccbill, clickbank, or google

Regarding the 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 have a Subscription ID. Use the Subscription ID if you have one — this is preferred by s2Member®.

Some payment gateways (other than PayPal®) may use a slightly different terminology for these values. For instance, ClickBank® uses a Receipt # 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.

Regarding the Optional `First Payment Date(s)` Value

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 re-importation. 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 In A CSV Import File

The way s2Member® Pro dealt with Custom Registration/Profile Fields in previous versions, was somewhat confusing to site owners (particularly when it came to User/Member Export files). We improved upon this in s2Member® Pro v130203 (and newer). If you are using a previous release, please click the other tab to see the older explanation of how this works.

Updated Documentation for s2Member® Pro v130203+

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: 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: s2Member -> General Options -> Registration/Profile Fields.

Here Is 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).

The 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 30052.

...,"fishing,biking,computers","xx-large","30052"
		

If you have any trouble understanding this, please do a full export of all Users/Members 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 re-importation. If you have Custom Registration/Profile Fields configured with s2Member®, 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.

The way s2Member® Pro dealt with Custom Registration/Profile Fields in previous versions, was somewhat confusing to site owners (particularly when it came to User/Member Export files). We improved upon this in s2Member® Pro v130203 (and newer). This tab exists for those of you still running earlier versions of s2Member® Pro. This documentation is now outdated. Please upgrade to s2Member® Pro v130203+.

Prior to s2Member® Pro v130203 (the old explanation)

The end of each line in a CSV import file, can include Custom Registration/Profile Fields (optional of course). The excerpt below, is taken from the full example in your Dashboard with extended details. You can see here that s2Member® Pro expected the following format with respect to Custom Registration/Profile Fields.

...,"Custom Field ID #1","Custom Field Value #1","Custom Field ID #2","Custom Field Value #2", ... 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: Dashboard -› s2Member® -› General Options -› Registration/Profile Fields.

What was confusing to site owners, was the way s2Member® Pro received the Custom Registration/Profile Field ID in a CSV import file (and not just the value). In the example here, we see that s2Member® expected to receive a comma-delimited list of Custom Registration/Profile Fields, where the unique Registration/Profile Field ID was listed first, and then followed by the value for that Registration/Profile Field ID. As noted below, this created some problems.

If I had two Custom Registration Profile Fields. One with a unique ID interests, and another with a unique ID t_shirt_size, this is how I would have constructed my CSV data for these fields (see the following example). The unique ID came first, followed by the value for that ID. In the following example with values filled in, the Custom Registration/Profile Field with ID interests was set to a value of fishing,biking,computers, and the value of t_shirt_size was set to xx-large.

...,"interests","fishing,biking,computers","t_shirt_size","xx-large"
		

This outdated format (which was also used in s2Member’s CSV export file), created a few problems. Some Users/Members did not have all of the Custom Registration/Profile Field values (because maybe they had not filled them in, or they did not apply at a specific Membership Level); and even if they did, the data was not stored in proper columns. This was troublesome for site owners editing their CSV export file in applications like MS Excel or OpenOffice. Fixed in s2Member® Pro v130203+. Thanks for your patience.

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: places_lived

...,"a:3:{i:0;s:7:"Florida";i:1;s:7:"Georgia";i:2;s:6:"Alaska";}"

Having Trouble Structuring Your CSV Import File?

Do not fear. If you have any trouble, please perform an export first using s2Member® Pro. s2Member’s export files are already formatted for easy re-importation. In other words, you can use them as a guideline for building your own import files.

About the Author

Jason (Lead Developer)Yep, I'm one of those oddball coders! When I'm not coding, I'm thinking about code, or helping others with code. Heck, sometimes my dreams are in the PHP language :-) It's been a passion of mine for 12+ years now.View all posts by Jason (Lead Developer) →

Contacting s2Member: Please use our Support Center for bug reports, pre-sale questions & technical assistance.