User Preferences

In this guide, you'll learn about user preferences in the Settings Module.

What is a User Preference?#

A user preference stores an arbitrary setting for a user as a key-value pair. For example, you can store a user's preferred theme or language.

The UserPreference data model represents a user preference. It denotes the user it belongs to through the user_id property, and it stores the setting's key and value in its key and value properties. A user can have only one preference per key.

Manage User Preferences#

The Settings Module's service provides methods to create, retrieve, update, and delete user preferences. Resolve the service from the Medusa container using Modules.SETTINGS.

Set a User Preference#

Use the setUserPreference method to create or update a user preference by its key:

Code
1const preference = await settingsModuleService.setUserPreference(2  "user_123",3  "theme",4  { mode: "dark" }5)

Get a User Preference#

Use the getUserPreference method to retrieve a user's preference by key:

Code
1const preference = await settingsModuleService.getUserPreference(2  "user_123",3  "theme"4)

This returns null if no preference exists for the specified user and key.

Create User Preferences#

Use the createUserPreferences method to create one or more preferences at once:

Code
1const preferences =2  await settingsModuleService.createUserPreferences([3    {4      user_id: "user_123",5      key: "theme",6      value: "dark",7    },8  ])

Retrieve a User Preference by ID#

Use the retrieveUserPreference method to retrieve a preference by its ID:

Code
1const preference =2  await settingsModuleService.retrieveUserPreference("uspref_123")

List User Preferences#

Use the listUserPreferences method to list preferences with optional filters:

Code
1const preferences =2  await settingsModuleService.listUserPreferences({3    user_id: "user_123",4  })

To retrieve a paginated list with the total count, use listAndCountUserPreferences:

Code
1const [preferences, count] =2  await settingsModuleService.listAndCountUserPreferences(3    { user_id: "user_123" },4    { take: 20, skip: 0 }5  )

Update User Preferences#

Use the updateUserPreferences method to update existing preferences by their IDs:

Code
1const preferences =2  await settingsModuleService.updateUserPreferences([3    {4      id: "uspref_123",5      value: "light",6    },7  ])

Delete User Preferences#

Use the deleteUserPreferences method to delete preferences by their IDs:

Code
await settingsModuleService.deleteUserPreferences("uspref_123")

Internal Usage#

The Settings Module uses user preferences internally to track a user's active view for an entity and active layout scope for a zone.

Learn more about these concepts in the View Configurations and Layout Configurations documents.