Password Migration Strategy

Import legacy password hashes and migrate them to Emporix native security on first successful login, without forcing a password reset.

Password migration strategy lets you move customers from a legacy commerce system to Emporix without forcing a password reset. You import existing password hashes, customers log in with their current credentials, and Emporix upgrades each password to the native security format in the background.

• Looking for API documentation? Check out the Customer Service (Tenant Managed) Tutorial.
• To use custom email templates or storefront redirects, see Mailjet and contact the Emporix Support Team.

Purpose

Password migration functionality is designed for platform migrations where you need to preserve the existing login experience, for example, when you move from a third party ERP system.

Emporix stores password hashes, not plain-text passwords. Emporix rehashes a password only when the customer logs in and submits it. Until that first successful login, Emporix verifies credentials against the imported legacy hash.

Features

Feature	Description
Transparent lazy rehash	After the first successful login, Emporix converts the password to the native security format automatically. The customer does not take extra steps.
Legacy hashing algorithms	Emporix verifies imported hashes with a registry of legacy methods, for example, Hybris SHA-512, during the retention window without changing the core login flow.
Scoped batch import	A dedicated, scoped endpoint imports customers in batches of up to 200, including hashes and metadata, without sending welcome emails.
Security parity	Login failures and lockout handling are the same for legacy and native authentication, so the migration window does not create a weaker path.

Typical use cases:

• Moving from a legacy commerce system to Emporix while keeping the existing login experience
• Bringing customer data from acquired companies or other platforms that use different authentication methods into a single Emporix tenant

How it works

The functionality has two stages:

Migration retention configuration

When imported accounts use a hashing mechanism other than the Emporix native format, configure a retention window. The configuration includes a retention end date and an optional reminder date. You can create or update the configuration with an upsert endpoint and remove it with a delete endpoint.

Bulk customer import

Insert up to 200 customers per request, including legacy password hashes and related metadata such as salts. This import does not trigger extra onboarding logic, such as welcome emails.

You can configure retention yourself through the API. Emporix can also configure it on your behalf. To use custom email templates and storefront redirects, contact the Emporix Support Team.

The retention timeline is as follows:

Customer experience

1

Silent period

Until the reminder date, migration is silent. Customers who log in keep using their existing password. Emporix validates the password with the legacy method and rehashes it to the native format in the background. No email is sent.

2

Reminder to log in

On the reminder date, customers who have not logged in yet receive an email that asks them to log in. The email includes the deadline and states that they must reset their password if they do not log in before retention ends.

The reminder date is the date you set in the retention configuration. If you omit it, the default is one week before the retention end date.

3

Thank-you after a late login

A customer who logs in between the reminder email and the retention end date receives a thank-you email. The email confirms that they do not need to take further action. Customers who already logged in before the reminder do not receive this email.

4

Retention end

When the retention end date is reached:

• Emporix deletes the legacy hashes you imported. Only hashes in the native Emporix format remain.
• Customers who still have not logged in can no longer log in with the old password. They must reset their password.
• Those customers receive an email that tells them they must reset their password.

How to set up password migration

Configure the retention window and import customers with legacy hashes through the Customer Service tenant-managed APIs. For the endpoint sequence, scopes, and request examples, see the Customer Service (Tenant Managed) Tutorial.

After import, the retention window runs automatically. See Customer experience for the silent period, reminder and thank-you emails, and retention end.

Contact the Emporix Support Team when you need assistance with:

• Changing the Mailjet templates for the login reminder, thank-you, or password-reset emails
• Adding storefront redirects so the reminder email opens the login page and the reset-required email opens the password-reset page

These emails are sent once during migration. Template and redirect changes are not self-service.