How Order Code Generation Works in SAP Commerce Cloud (Step-by-Step Guide)

1. What is an Order Code in SAP Commerce?

An order code is a unique identifier assigned to every order placed in the system.

Example:

00000012
00000013
U00000000000123

By default, SAP Commerce generates numeric order codes, but this can be customized to:

• Change length (digits)
• Add prefixes (e.g., country-based)
• Use alphanumeric formats

2. Where Does Order Code Generation Happen?

Order code generation happens during order placement, typically in the service layer.

Internally, SAP Commerce uses a Key Generator mechanism, specifically:

👉 PersistentKeyGenerator

This class is responsible for generating unique, sequential values using database-backed number series.

3. Key Configuration Properties

SAP Commerce makes order code generation configurable using properties.

You can find or override these in:

hybris/config/local.properties

Important Properties

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

Explanation

• digits → Total length of the order code
• start → Starting value of the sequence
• type → Format (numeric or alphanumeric)

4. How PersistentKeyGenerator Works

At the core of order code generation is:

👉 PersistentKeyGenerator

What it does:

• Reads configuration properties
• Maintains a number series in the database
• Generates the next unique value
• Ensures no duplicates (even in concurrent environments)

Flow:

1. Order is placed
2. System calls key generator
3. Generator fetches current value from DB
4. Increments value
5. Returns new order code

5. Spring Bean Configuration (core-spring.xml)

Order code generation is wired using Spring configuration.

Example:

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

This bean connects:

• Configuration properties
• Generator logic
• Order creation flow

6. Database-Level Storage (Number Series)

SAP Commerce stores sequence values in a number series table.

This ensures:

• Persistence across restarts
• Thread-safe increments
• Unique values across cluster nodes

7. Customizing Order Code Generation

One of the biggest strengths of SAP Commerce is flexibility.

You can customize order codes in multiple ways:

✅ Change Length

keygen.order.code.digits=12

✅ Change Format

keygen.order.code.type=alphanumeric

✅ Add Prefix (via customization)

Example:

U000000000123 (US)
I000000000456 (IN)

8. Advanced Customization (Real-World Scenario)

In real projects, businesses often require:

• Country-specific order formats
• Channel-based prefixes
• Different formats per website

This can be achieved by:

• Creating multiple key generators
• Extending PersistentKeyGenerator
• Overriding the generate() method

We’ll cover this in the next article.

9. Common Issues & Fixes

❌ Order number not changing

• Check local.properties
• Verify Spring bean configuration

❌ Changes not reflecting after restart

• Ensure properties are in local.properties (not project.properties)

❌ Need to reset sequence

• Use Groovy script with NumberSeriesManager

10. Best Practices

• Always use local.properties for overrides
• Avoid modifying project.properties (lost during upgrades)
• Keep order codes meaningful but simple
• Use customization only when required

Conclusion

Order code generation in SAP Commerce Cloud is:

• Config-driven
• Database-backed
• Highly customizable

Understanding this mechanism helps you:

• Debug issues faster
• Implement real-world business logic
• Build scalable solutions

What’s Next?

In the next article, we’ll cover:

👉 How to Customize Order Number Format in SAP Commerce (Digits, Prefix, Alphanumeric)