Importing users in bulk using a CSV file

You can import a CSV file from your Shopify admin to create new admin users or Point of sale (POS) users for Shopify POS, and manage their store access in bulk.

You can use a CSV import to make the following changes to your user accounts:

• Create new admin users
• Create new Point of sale (POS) users for Shopify POS with assigned PINs
• Suspend and reactivate existing admin and POS user accounts

Considerations for the user management CSV file

Some changes to user accounts aren't supported by a CSV import. For updates that a CSV import can't complete, manage your user accounts manually in your Shopify admin or in the Shopify POS app. Review the following considerations when you import users using a CSV file:

• The CSV file import doesn't support bulk deletion of users.
• You can't set or update two-factor authentication requirements for users.
• You can't change an existing user's PIN for Shopify POS.
• You can't create new roles, groups, or locations from a CSV import. Role names, group names, and location names in your file must match what already exists in your Shopify admin.
• You can only suspend or reactivate existing users with a CSV import. You can't change an existing user's role, assigned group, location, or store access.
• You can't change a user's type, such as changing a POS-only user to an admin user.

Download a sample user management CSV file

A sample file includes the required column headers and example values for each column. You can use it as a starting point before you add your own users.

You can download and view a sample user management CSV file from this page, or download a sample from the Import page in your Shopify admin.

To learn how to save and edit CSV files in your spreadsheet app, refer to Open and edit a CSV file.

Column definitions for the user management CSV file

The following table lists every column in the sample user management CSV file. Each definition explains how the column is used when you create users, or when you suspend or reactivate existing users, including differences between admin users and POS-only users.

Create new users in a CSV file

To create a new user, leave id blank on that row. After the user is created, the import automatically assigns a value to id.

To grant users access to more than one location, role, or store, refer to Assigning multiple roles, locations, and stores to a user.

Create a POS user

To create a POS user, enter a value for the following fields:

• Enter Point of sale in user_type.
• Enter given_name and family_name.
• To set user permissions, enter a value for one of the following fields:
  • role_name and store_name: If your organization has more than one store, then both fields are required.
  • group_name: Available only on the Shopify Plus plan. To learn how to assign a group, refer to Assigning a group to a user in a CSV file.
• To set location access, enter a value for the following fields:
  • For access to specific locations, enter pos_location_name, and set all_current_and_future_locations to FALSE.
  • For access to all locations, set all_current_and_future_locations to TRUE, and leave pos_location_name blank.
• Optional: Enter email, phone, or pin. A PIN must be a 4–6-digit number that is unique within a store.

Create an admin user

To create an admin user, enter a value for the following fields:

• Enter Admin in user_type.
• Enter email.
• To set user permissions, enter a value for the following fields:
  • role_name and store_name: If your organization has only one store, then store_name isn't required. If the role is an organization-level role, then leave store_name blank.
  • group_name: Available only on the Shopify Plus plan. To learn how to assign a group, refer to Assigning a group to a user in a CSV file.
• Optional: When role_name is a POS-category role, you can enter a value for pin on that row. If you don't specify a PIN, then the import generates a PIN for the user.
• If role_name is a POS-category role, then you must set location access for the user. Enter a value for the following fields:
  • For access to specific locations, enter pos_location_name, and set all_current_and_future_locations to FALSE.
  • For access to all locations, set all_current_and_future_locations to TRUE, and leave pos_location_name blank.

Suspend or reactivate existing users in a CSV file

You can suspend or reactivate an existing user by adding one row per user to your user management CSV file. Users are identified by id.

To suspend or reactivate an existing user, enter a value for the following fields:

• Enter the id for the user.
• Enter the user_type for the user.
• If the user is an admin user, then enter a value for the following fields:
  • email: Required.
  • given_name: Optional. If you enter a value, then it must match the user's first name in your Shopify admin.
  • family_name: Optional. If you enter a value, then it must match the user's last name in your Shopify admin.
  • phone: Optional. If you enter a value, then it must match the user's phone number in your Shopify admin.
• If the user is a POS user, then enter a value for the following fields:
  • given_name: Required.
  • family_name: Required.
  • email: If the user has an email on their account, then this field is required.
  • phone: If the user has a phone number on their account, then this field is required.
• status: Enter Suspended to suspend the user, or Active to reactivate the user. You can suspend a user only when their current status is Active or Inactive in your Shopify admin. You can reactivate a user only when their current status is Suspended.

Assigning multiple roles, locations, and stores to a user

When you create a new user, you can assign more than one role, POS location, and store to that user in a single CSV file import. Each role, location, or store combination needs its own row in the file.

Add one row for each value that you want to assign to the same user. On every row for that user, enter the same identification values so the import applies every row to that one user account. Leave id blank on every row. The import assigns id after the user is created.

Identification values required on every row

For the import to identify the same user, enter the following values on every row of your CSV file for that user:

• For admin users, the same email and user_type must be entered on every row for that user.
• For POS users, the same user_type, given_name, family_name, email, and phone must be entered for that user on every row.

Assigning multiple roles to a user in the same store

A single user can hold more than one role at the same store when each role is represented on its own row in the CSV file.

To assign a user more than one role at the same store, you must add one row per role in your CSV file. On every row, enter the same identification values for that user, and then include the exact store_name and role_name that are listed in your Shopify admin.

Assigning multiple POS locations in the same store

When a user should access only certain POS locations in a store, you list each location on a separate row.

To assign a user access to multiple specific POS locations, you must add one row per location in your CSV file. On every row, enter the same identification values for that user, enter the pos_location_name that is listed in your Shopify admin, and set all_current_and_future_locations to FALSE on each row.

For example, to give a user the same role at two specific locations in one store, add one row per location.

Alternatively, to grant access to all current and future locations, use a single row with all_current_and_future_locations set to TRUE and pos_location_name left blank. Use the same TRUE or FALSE value on every row for that user in that store. You can't mix them between rows.

Assigning user access across multiple stores

Organizations with more than one store can grant the same person access in each store that they need.

When the same user needs access in more than one store, use one row per role-store-location combination. On every row, you must enter the same identification values for that user, along with the exact store_name that is listed in your Shopify admin.

You can assign multiple roles and multiple POS locations to the same user for each store.

For all_current_and_future_locations and pos_location_name on create rows, use the same row patterns as in assigning multiple POS locations in the same store. You can't set all_current_and_future_locations to TRUE when pos_location_name has a value on that row.

The following example assigns the same POS user with different location access across two different stores.

If any row for a user fails, then all rows for that user are rejected. After you fix the error, include every row for that user in the next import.

Assigning a group to a user in a CSV file

Groups are available only for organizations on the Shopify Plus plan. A group bundles one or more roles, so assigning a group can grant a user several roles at the same time.

Assigning a group or a single role

Each row in a CSV file can assign either a group or a single role, but not both:

• To assign a group, enter the group in group_name and leave role_name blank.
• To assign a single role, enter the role in role_name and leave group_name blank.

Assigning a group to eligible users

You can assign a group to a user when at least one role in the group applies to that user's type. Roles in the group that don't apply to the user's type aren't granted, but they don't cause an error. The group still assigns successfully based on the roles that apply.

You can't assign a group that has no roles.

Assigning a group across stores and locations

You must include a row in your CSV file for each store where the group grants a POS role. On each of those rows, you must also set location access:

• For access to specific locations, enter pos_location_name, and set all_current_and_future_locations to FALSE. To grant several specific locations in one store, add one row per location, with the same group and store on each row.
• For access to all locations, set all_current_and_future_locations to TRUE, and leave pos_location_name blank.

Location access for a group is validated the same way as a POS role that isn't assigned through a group, including that it can't conflict with location access that the same user is granted on another row.

Setting PINs when assigning a group

A PIN follows the same rules that apply to users with multiple roles:

• Enter a pin only on a row in your CSV file for a store where the group grants a POS role.
• A PIN must be unique within a store, but can differ across stores.
• Don't enter a pin on a row for a store where the group grants only non-POS roles.

Assigning a group that includes an organization role

When a group includes an organization role that has POS permissions, the organization role automatically grants access to all locations, so the per-store location requirement doesn't apply to it. You can assign this type of group in one of the following ways:

• A single group-only row: Enter the group in group_name, and leave store_name, pos_location_name, all_current_and_future_locations, and pin blank. The organization role grants access to all locations automatically.
• Explicit store rows: Add a row for each store where the group grants a POS role. On every one of these rows, set all_current_and_future_locations to TRUE. You can't limit a user with an organization role to a single location.

Examples of assigning a group

The following examples illustrate how to assign one group across different stores and locations. Each row lists the values for group_name, store_name, pos_location_name, and all_current_and_future_locations.

In the following examples, the group grants a store role and a POS role in Store 1, and a POS role in Store 2:

• Example 1 assigns the group with access to all locations in two stores. Because the group grants a POS role in each store, you must add one row per store in your CSV file.

• Example 2 assigns the group in two stores, but the group grants a POS role only in Store 1 and a store-only role in Store 2. Add a row in your CSV file only for the store with a POS role. The store-only role in Store 2 is granted without a row.

• Example 3 assigns the group with access to specific locations in two stores. You must add one row in your CSV file per location.

• Example 4 assigns a group that includes an organization role with POS permissions, in addition to a store role and a POS role. You can assign this group in one of the following ways:

  • The first option is a single group-only row, where the organization role grants access to all locations.
  • The second option uses an explicit row for each store where the group grants a POS role. On each row, all_current_and_future_locations must be TRUE, because the organization role can't be limited to a single location.

Import a user management CSV file from your Shopify admin

After you build your CSV file and save it in the correct format, you can upload it from your organization Users page. The import runs in your Shopify admin and reports any rows that can't be processed.

Steps:

1. From your Shopify admin, go to Settings > Users.

2. Click Import.

3. Optional: Click the link to download a sample CSV file, and then use it as a template for your own file.

4. Click Upload file, and then select your .csv file.

After the import completes, review the confirmation in your Shopify admin. If any rows have errors, then you receive an email with details so you can correct your file and import again.

Solutions to common user management import issues

If you're having a problem uploading your user management CSV file, then check if the problem is listed in the following solutions.

When you need help with troubleshooting a specific error message, refer to Troubleshooting import error messages.

Re-importing after fixing errors

When an import is unsuccessful, you receive an email that lists the rows that failed. Re-import your file carefully so that you don't create duplicate users.

Re-import only the users that had errors, not the entire file. Use the following practices:

• Fix the rows that failed, and then include every row for each affected user in your new file. If a user had 3 rows and 1 row caused an error, then all 3 rows for that user were rejected. Include all 3 corrected rows in your re-import.
• Don't include users that imported successfully. Those accounts already exist. Importing them again can return a user already exists error, create duplicate users, or both.

If you re-import the entire original file, including rows for users that were already created successfully, then you might encounter the following outcomes:

• Admin users: If an email address is already in use, then you might receive a user already exists or duplicate email error.
• POS users: The system can create duplicate POS user records. POS users are matched using name and related fields instead of a unique email, so a second user can be created with the same name and role.
• Seat limits: If the import counts users that were already created, then you might receive seat limit errors. To learn more, refer to maximum number of users for each pricing plan.

Creating multiple POS users with the same name

If the identification values for a POS user match on multiple rows in one import, including non-consecutive rows, then the import treats those rows as the same user.

To create separate POS users with the same given_name and family_name in one import, you must enter a different value for at least one of the following fields for each user:

• email
• phone

If you can't distinguish multiple users with the same given_name and family_name using different values for email or phone, then you must import each user in a separate CSV file.

File format and upload size

The following issues relate to the CSV file format or size, not to the values in your user rows:

• Wrong file format: Your file must be a .csv file saved with the encoding described in Open and edit a CSV file.
• File is too large: If your file has many rows, then split it into smaller files and import them one at a time.

POS user displays as multiple users instead of one multi-role user

The import matches rows to the same POS user when user_type, given_name, family_name, email, and phone match on every row for that person. If any of these values differ between rows, then the import creates separate users.

The following situations often lead to duplicate POS users when you expected one multi-role user:

• Email on one row but not another: If you include email on the first row for a POS user but leave it blank on another row, then the import creates separate users. Include email on every row for that user, or leave it blank on every row.
• Typo in the name: A typo in the name rows might create separate users. For example, Jane on one row and jane on another row might be treated as different users if matching is case-sensitive. Write the user's name the same way on every row.
• Phone on one row but not another: If you include phone on the first row for a POS user but leave it blank on another row, then the import creates separate users. Include phone on every row for that user, or leave it blank on every row.

To avoid duplicating users, make sure user_type, given_name, family_name, email, and phone are identical on every row for the same POS user in your CSV file.

Seat limit errors

Seat limits apply to admin users on your organization's pricing plan. When you receive a seat limit error during an import, the import counts how many new admin users your file would create, and checks that number against your plan's seat limit. If you're at or near your seat limit, then reduce the number of new admin users in your CSV, or review user limits for your pricing plan before you import again.

Export your user list to find duplicate POS users

You can export your user list to a CSV file and compare rows in a spreadsheet when you suspect duplicate POS users. The export includes timestamps that indicate which account was created first.

To learn how exports are delivered and who can download them, refer to exporting your user management information as a CSV file.

Steps:

1. From your Shopify admin, go to Settings > Users.

2. Click Export.

3. In the Export users dialog, click Export.

4. When you receive the email, click Download file to save the CSV to your device.

5. Open the file in a spreadsheet app, and then sort by the GIVEN_NAME column.

6. Review POS users with matching given name, family name, email, and phone values in the export that have CREATED_AT times that are the same or very close together. These accounts are likely duplicates.

Delete duplicate POS users manually

You can remove a duplicate POS user account manually in your Shopify admin without using a CSV file.

Steps:

1. From your Shopify admin, go to Settings > Users.

2. Select the duplicate user account.

3. Click Remove.

Bulk delete duplicate POS users using a CSV file

You can suspend duplicate accounts with a CSV import, and then delete those suspended accounts in bulk from the Users page in your Shopify admin. Suspending the accounts first helps you confirm which accounts you're removing before you delete them.

Steps:

1. Export your current user list.
2. Identify duplicate accounts using the comparison method described in Export your user list to compare duplicate POS users.
3. For each duplicate account, copy the values for id, user_type, email, phone, given_name, and family_name into a new CSV file. Use the same column structure as the sample user management CSV file.
4. Set status to Suspended for each duplicate row. Leave role_name, group_name, store_name, pos_location_name, all_current_and_future_locations, and pin blank.
5. Import the CSV file to suspend those users.
6. Go to Settings > Users.
7. If available, filter the user list to Suspended accounts. Select the duplicate accounts that you suspended, and then delete them in bulk.

Troubleshooting import error messages

When a user management CSV import is unsuccessful, you receive an email that includes the error message and the affected rows. The following sections explain what each type of message means and what you can change in your CSV file before you import again.

If you're still having problems with your CSV import, then contact Shopify Support.

CSV file errors

User identification errors

Admin or POS user creation errors

The following troubleshooting applies when the id field for the user is blank to create a new user.

Admin user creation errors

The following troubleshooting applies when id is blank and user_type is set to Admin.

POS user creation errors

The following troubleshooting applies when id is blank and user_type is set to Point of sale.

User suspension errors

The following troubleshooting applies when id has a value and you're changing status for an existing user.