SCsapcommercejobs
Blogsap commerce cloud

sap commerce cloud

PersistentKeyGenerator in SAP Commerce Cloud Explained (Complete Guide)

If you’ve worked with order code generation in SAP Commerce Cloud, you’ve likely encountered PersistentKeyGenerator. It’s the core component responsible for generating unique, sequential values like order numbers. In this guide, we’ll break down how it works internally and how you can customize it for real-world use cases.

Av
Avinash Jadhav

May 1, 2026•2 min read

1. What is PersistentKeyGenerator?

PersistentKeyGenerator is a built-in SAP Commerce class used to generate:

  • Order codes
  • Cart IDs
  • Consignment numbers
  • Any sequential unique identifiers

It ensures:

  • Uniqueness
  • Persistence
  • Thread safety

2. Why “Persistent”?

Unlike in-memory generators, this one stores values in the database.

👉 This means:

  • Values persist after server restart
  • Works in clustered environments
  • No duplicate values

3. How It Works (Internal Flow)

Here’s the simplified flow:

  1. Request for new key (e.g., order placement)
  2. Generator checks number series in DB
  3. Fetches current value
  4. Increments it
  5. Returns new value

4. Number Series Concept

SAP Commerce uses NumberSeries internally.

Each generator is linked to a unique key:

order_code
cart_code
consignment_code

Each key maintains:

  • Current number
  • Start value
  • Type (numeric/alphanumeric)

5. Configuration Properties

Defined in:

local.properties

Example:

keygen.order.code.digits=8
keygen.order.code.start=00000000
keygen.order.code.type=numeric

6. Spring Bean Configuration

Typical bean setup:

<bean id="orderCodeGenerator" class="de.hybris.platform.servicelayer.keygenerator.impl.PersistentKeyGenerator">
    <property name="key" value="order_code"/>
    <property name="digits" value="${keygen.order.code.digits}"/>
    <property name="start" value="${keygen.order.code.start}"/>
    <property name="type" value="${keygen.order.code.type}"/>
</bean>

7. Key Properties Explained

  • key → Unique identifier for number series
  • digits → Length of generated value
  • start → Initial value
  • type → numeric or alphanumeric

8. Real Example

If configured as:

keygen.order.code.digits=8
keygen.order.code.start=00000000

Generated values:

00000001
00000002
00000003

9. Customizing PersistentKeyGenerator

You can extend this class for custom logic.

Example:

public class CustomOrderCodeGenerator extends PersistentKeyGenerator {

    @Override
    public String generate() {
        String code = super.generate().toString();
        return "ORD-" + code;
    }
}

👉 Output:

ORD-00000001

10. Advanced Use Cases

  • Multi-site order generation
  • Country-specific prefixes
  • Channel-based identifiers
  • Business-specific formatting

11. Resetting Number Series (Groovy)

You can reset sequence using Groovy:

numberSeriesManager.resetNumberSeries("order_code", "10000000", "numeric", null)

👉 Useful for:

  • Testing
  • Data correction

12. Common Issues

❌ Duplicate keys
→ Wrong key configuration

❌ Sequence not updating
→ Check DB / number series

❌ Changes not applied
→ Restart server or verify config

13. Best Practices

  • Use unique keys per generator
  • Avoid modifying default behavior unless required
  • Keep logic simple
  • Always test in multi-node setup

Conclusion

PersistentKeyGenerator is a foundational component in SAP Commerce Cloud that enables reliable and scalable key generation. Once you understand how it works, you can easily customize order numbers and implement advanced business logic.

What’s Next?

👉 Next: How to Reset Order Number Sequence in SAP Commerce Using Groovy Script

Related Resources