From 1321cb76294f5b7bb9567fe3da179be584a1ec6e Mon Sep 17 00:00:00 2001 From: Matt Brailsford Date: Wed, 15 Oct 2025 14:14:08 +0100 Subject: [PATCH 01/12] Order number generator docs --- 16/umbraco-commerce/SUMMARY.md | 1 + .../order-number-customization.md | 99 +++++++- .../key-concepts/order-number-generators.md | 217 ++++++++++++++++++ 3 files changed, 308 insertions(+), 9 deletions(-) create mode 100644 16/umbraco-commerce/key-concepts/order-number-generators.md diff --git a/16/umbraco-commerce/SUMMARY.md b/16/umbraco-commerce/SUMMARY.md index 428365f1402..df68b58ccd3 100644 --- a/16/umbraco-commerce/SUMMARY.md +++ b/16/umbraco-commerce/SUMMARY.md @@ -74,6 +74,7 @@ * [List of notification events](key-concepts/events/list-of-notification-events.md) * [Fluent API](key-concepts/fluent-api.md) * [Order Calculation State](key-concepts/order-calculation-state.md) +* [Order Number Generators](key-concepts/order-number-generators.md) * [Payment Forms](key-concepts/payment-forms.md) * [Payment Providers](key-concepts/payment-providers.md) * [Pipelines](key-concepts/pipelines.md) diff --git a/16/umbraco-commerce/how-to-guides/order-number-customization.md b/16/umbraco-commerce/how-to-guides/order-number-customization.md index 21e8931b988..ada6bfeefcf 100644 --- a/16/umbraco-commerce/how-to-guides/order-number-customization.md +++ b/16/umbraco-commerce/how-to-guides/order-number-customization.md @@ -4,46 +4,122 @@ description: Learn how to customize the default order number generated in Umbrac # Order Number Customization -In Umbraco Commerce, the default order number generation can be customized by implementing the `IOrderNumberGenerator` interface. This interface defines two methods: `GenerateCartNumber(Guid storeId)` and `GenerateOrderNumber(Guid storeId)`, which you can override to create a custom numbering system.​ +Umbraco Commerce provides flexible options for customizing order numbers to meet your business requirements. This guide covers the various approaches from simple template customization to implementing fully custom generators. + +## Built-in Generators + +Before implementing a custom solution, understand that Umbraco Commerce includes two built-in order number generators: + +- **CompactSortableOrderNumberGenerator** (Recommended) - Produces compact, time-sortable identifiers with excellent scalability and multi-node support +- **DateHashOrderNumberGenerator** (Legacy) - Date-based format maintained for backward compatibility + +For detailed information about these generators and how they work, see the [Order Number Generators](../key-concepts/order-number-generators.md) key concepts documentation. + +## Before Creating a Custom Generator + +Consider these simpler alternatives before implementing a custom generator: + +### 1. Using Store Templates + +The simplest way to customize order numbers is through store-level templates. Templates allow you to add prefixes, suffixes, or formatting without writing any code: + +```csharp +// Configure templates via the Store entity +await store.SetCartNumberTemplateAsync("CART-{0}"); +await store.SetOrderNumberTemplateAsync("ORDER-{0}"); +``` + +**Examples:** +- Template: `"ORDER-{0}"` + Generated: `"22345-67ABC"` = Final: `"ORDER-22345-67ABC"` +- Template: `"SO-{0}-2025"` + Generated: `"12345"` = Final: `"SO-12345-2025"` + +This approach works with any generator and requires no custom code. + +### 2. Using CompactSortableOrderNumberGenerator + +The `CompactSortableOrderNumberGenerator` handles most common requirements: +- Compact format (10-11 characters) +- Time-sortable +- Multi-node safe +- High-volume capable (1,024 orders/sec per node) + +If your store was upgraded from an earlier version and is using the legacy generator, you can explicitly switch to the recommended generator: + +```csharp +public class MyComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + { + builder.Services.AddUnique(); + } +} +``` ## Implementing a Custom Order Number Generator -To create a custom order number generator, define a class that implements the `IOrderNumberGenerator` interface, for example, `CustomOrderNumberGenerator.cs`: +If the built-in generators don't meet your needs, you can create a custom implementation by implementing the `IOrderNumberGenerator` interface. + +### Creating the Custom Generator + +Define a class that implements the `IOrderNumberGenerator` interface: {% code title="CustomOrderNumberGenerator.cs" %} ```csharp +using System; +using System.Threading; +using System.Threading.Tasks; using Umbraco.Commerce.Core.Generators; +using Umbraco.Commerce.Core.Services; public class CustomOrderNumberGenerator : IOrderNumberGenerator { - public string GenerateCartNumber(Guid storeId) + private readonly IStoreService _storeService; + + public CustomOrderNumberGenerator(IStoreService storeService) { - // Implement custom logic for cart numbers + _storeService = storeService; } - public string GenerateOrderNumber(Guid storeId) + public async Task GenerateCartNumberAsync(Guid storeId, CancellationToken cancellationToken = default) { - // Implement custom logic for order numbers + var store = await _storeService.GetStoreAsync(storeId); + + // Implement your custom logic for cart numbers + var cartNumber = $"{DateTime.UtcNow:yyyyMMdd}-{Guid.NewGuid().ToString("N")[..8].ToUpperInvariant()}"; + + // Apply store template if configured + return string.Format(store.CartNumberTemplate ?? "{0}", cartNumber); + } + + public async Task GenerateOrderNumberAsync(Guid storeId, CancellationToken cancellationToken = default) + { + var store = await _storeService.GetStoreAsync(storeId); + + // Implement your custom logic for order numbers + var orderNumber = $"{DateTime.UtcNow:yyyyMMdd}-{Random.Shared.Next(1000, 9999)}"; + + // Apply store template if configured + return string.Format(store.OrderNumberTemplate ?? "{0}", orderNumber); } } ``` {% endcode %} -## Registering the Custom Implementation +### Registering the Custom Implementation After creating your custom generator, register it in `Program.cs` to replace the default implementation: {% code title="Program.cs" %} ```csharp -builder.Services.AddUnique(); +builder.Services.AddUnique(); ``` {% endcode %} -The `AddUnique` method ensures that your custom generator replaces the default `IOrderNumberGenerator`. For more details on dependency injection, see the [Dependency Injection](dependency-injection.md) article. +The `AddUnique` method ensures that your custom generator replaces the default `IOrderNumberGenerator`, overriding both the automatic selection system and the built-in generators. For more details on dependency injection, see the [Dependency Injection](dependency-injection.md) article. ## Important Considerations @@ -54,3 +130,8 @@ Before implementing a custom order number generator, be aware of the following: - **Accounting Considerations:** Umbraco Commerce is not designed as an accounting platform. If strict sequential numbering is required for accounting purposes, it is recommended to integrate with a dedicated accounting system to handle such requirements. By understanding these factors, you can implement a custom order number generator that aligns with your specific requirements while maintaining optimal performance and compliance. + +## Related Documentation + +- [Order Number Generators](../key-concepts/order-number-generators.md) - Detailed documentation about the built-in generators +- [Dependency Injection](dependency-injection.md) - Learn more about registering services in Umbraco Commerce diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md new file mode 100644 index 00000000000..6a16a649803 --- /dev/null +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -0,0 +1,217 @@ +--- +title: Order Number Generators +description: Documentation for IOrderNumberGenerator in Umbraco Commerce +--- + +# Order Number Generators + +Order Number Generators are responsible for generating unique, human-readable identifiers for carts and orders in Umbraco Commerce. These generators ensure that each cart and order receives a distinct number that can be used for tracking, customer communication, and administrative purposes. + +## IOrderNumberGenerator Interface + +The `IOrderNumberGenerator` interface defines the contract for generating order and cart numbers: + +```csharp +public interface IOrderNumberGenerator +{ + Task GenerateCartNumberAsync(Guid storeId, CancellationToken cancellationToken = default); + Task GenerateOrderNumberAsync(Guid storeId, CancellationToken cancellationToken = default); +} +``` + +The interface provides two key methods: + +- **GenerateCartNumberAsync** - Generates a unique number for shopping carts (orders that haven't been finalized) +- **GenerateOrderNumberAsync** - Generates a unique number for finalized orders + +Both methods are store-scoped, allowing different stores in a multi-tenant environment to have independent number sequences. + +## Built-in Generators + +Umbraco Commerce includes two built-in order number generators: + +### CompactSortableOrderNumberGenerator (Recommended) + +The `CompactSortableOrderNumberGenerator` is the recommended generator introduced in Umbraco Commerce 16.4. It produces compact, time-sortable identifiers with excellent scalability characteristics. + +**Format:** 10-character Base32 encoded ID with hyphen formatting + +Where: +- **timeComponent** - 7 Base32 characters encoding seconds since January 1, 2025 (supports ~1089 years) +- **nodeId** - 1 Base32 character representing the server/node ID (0-31) +- **sequence** - 2 Base32 characters encoding a per-second sequence number (0-1023) + +**Example:** `22345-67ABC` (hyphen inserted at position 5 for readability) + +**Characteristics:** +- **Compact** - Only 10 characters (11 with hyphen formatting) +- **Time-sortable** - Lexicographic ordering matches chronological ordering +- **Scalable** - Supports up to 1,024 orders per second per node (gracefully waits for the next second if capacity is exceeded rather than failing) +- **Multi-node safe** - Node ID prevents collisions in clustered environments +- **Visual variety** - Character rotation based on time reduces visual repetition + +**Base32 Alphabet:** Uses Crockford-like Base32 (`23456789ABCDEFGHJKLMNPQRSTUVWXYZ`) which excludes ambiguous characters (0, 1, I, O). + +**Number Template Support:** +Cart and order numbers can be formatted using the store's `CartNumberTemplate` and `OrderNumberTemplate` settings (defaults: `"CART-{0}"` and `"ORDER-{0}"`). + +### DateHashOrderNumberGenerator (Legacy) + +The `DateHashOrderNumberGenerator` is the legacy generator from earlier versions of Umbraco Commerce. It creates order numbers based on the current date and time, combined with a random string component. + +{% hint style="info" %} +**Note:** This generator is maintained for backward compatibility with existing stores but will eventually be obsoleted. New implementations should use `CompactSortableOrderNumberGenerator`. +{% endhint %} + +**Format:** `{dayCount:00000}-{timeCount:000000}-{randomString}` + +Where: +- **dayCount** - Number of days since January 1, 2020 (5 digits) +- **timeCount** - Number of seconds elapsed in the current day (6 digits for carts, 5 for orders) +- **randomString** - 5 random characters from the set `BCDFGHJKLMNPQRSTVWXYZ3456789` + +**Example:** `02103-45678-H4K9P` + +**Characteristics:** +- Human-readable with embedded date information +- Random component reduces predictability +- No sequential ordering within the same second +- Collision risk increases if multiple orders are placed simultaneously +- Not suitable for high-volume or multi-node scenarios + +## How Generators Are Chosen + +Since Umbraco Commerce 16.4, the platform automatically selects the appropriate generator based on your store's state: + +- **New installations (16.4+)** - Uses `CompactSortableOrderNumberGenerator` for all new stores +- **Upgrades with existing orders** - Continues using `DateHashOrderNumberGenerator` for stores that already have orders, ensuring consistent number formats +- **Upgrades without orders** - Switches to `CompactSortableOrderNumberGenerator` for stores with no existing orders + +Prior to version 16.4, all installations used `DateHashOrderNumberGenerator` by default. + +This automatic selection ensures backward compatibility while enabling improved functionality for new stores. + +## Explicitly Choosing a Generator + +If you want to explicitly choose which generator to use, you can override the registration in your application startup. + +### Using CompactSortableOrderNumberGenerator (Recommended) + +To explicitly use the compact sortable generator (for example, when migrating an existing store to the new format): + +```csharp +public class MyComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + { + builder.Services.AddUnique(); + } +} +``` + +### Using DateHashOrderNumberGenerator (Legacy Only) + +Only use this if you need to maintain the legacy format on a system that was upgraded: + +```csharp +public class MyComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + { + builder.Services.AddUnique(); + } +} +``` + +{% hint style="warning" %} +**Warning:** Changing the order number generator on an existing store will result in different number formats for new orders. Ensure your business processes and integrations can handle mixed formats before making changes. +{% endhint %} + +## Creating a Custom Generator + +You can create custom order number generators by implementing the `IOrderNumberGenerator` interface: + +```csharp +public class CustomOrderNumberGenerator : IOrderNumberGenerator +{ + private readonly IStoreService _storeService; + + public CustomOrderNumberGenerator(IStoreService storeService) + { + _storeService = storeService; + } + + public async Task GenerateCartNumberAsync(Guid storeId, CancellationToken cancellationToken = default) + { + var store = await _storeService.GetStoreAsync(storeId); + + // Your custom cart number generation logic + var cartNumber = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant(); + + // Apply store template if configured + return string.Format(store.CartNumberTemplate ?? "{0}", cartNumber); + } + + public async Task GenerateOrderNumberAsync(Guid storeId, CancellationToken cancellationToken = default) + { + var store = await _storeService.GetStoreAsync(storeId); + + // Your custom order number generation logic + var orderNumber = DateTime.UtcNow.ToString("yyyyMMdd") + "-" + + Random.Shared.Next(1000, 9999); + + // Apply store template if configured + return string.Format(store.OrderNumberTemplate ?? "{0}", orderNumber); + } +} +``` + +### Registering a Custom Generator + +Register your custom generator during application startup to replace the default implementation: + +```csharp +public class MyComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + { + builder.Services.AddUnique(); + } +} +``` + +### Important Considerations for Custom Generators + +When implementing a custom generator, ensure: + +1. **Uniqueness** - Generated numbers must be globally unique across all time +2. **Consistency** - The same store should produce numbers in a consistent format +3. **Thread-safety** - Handle concurrent calls safely, especially for sequential numbering +4. **Template support** - Apply the store's `CartNumberTemplate` and `OrderNumberTemplate` settings +5. **Store isolation** - Consider supporting store-specific sequences in multi-store scenarios +6. **Scalability** - Handle high-volume scenarios if your store expects significant traffic +7. **Cluster-awareness** - In multi-node environments, ensure numbers don't collide across nodes +8. **Readability** - Balance uniqueness with human readability for customer communication + +{% hint style="warning" %} +**Important:** Order numbers may have gaps if customers cancel or modify orders during the checkout process. Umbraco Commerce is not designed as an accounting platform. If you require strict sequential numbering for accounting purposes, integration with a dedicated accounting system is recommended. Additionally, sequential numbering can impact performance due to potential database access requirements. +{% endhint %} + +## Configuration + +Order number templates are configured at the store level and provide a way to add prefixes or suffixes to generated numbers: + +```csharp +// Set via the Store entity +await store.SetCartNumberTemplateAsync("CART-{0}"); +await store.SetOrderNumberTemplateAsync("ORDER-{0}"); +``` + +The `{0}` placeholder is replaced with the generated number from the active generator. + +**Examples:** +- Template: `"ORDER-{0}"` + Generated: `"22345-67ABC"` = Final: `"ORDER-22345-67ABC"` +- Template: `"{0}"` + Generated: `"02103-45678-H4K9P"` = Final: `"02103-45678-H4K9P"` +- Template: `"SO-{0}-2025"` + Generated: `"12345"` = Final: `"SO-12345-2025"` + +Templates are applied regardless of which generator is active, providing consistent branding across your order numbers. From ae19af33f48206f39801d620a2450ad9521351d3 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:26:05 +0200 Subject: [PATCH 02/12] Update 16/umbraco-commerce/how-to-guides/order-number-customization.md --- 16/umbraco-commerce/how-to-guides/order-number-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/how-to-guides/order-number-customization.md b/16/umbraco-commerce/how-to-guides/order-number-customization.md index ada6bfeefcf..8adaeacf679 100644 --- a/16/umbraco-commerce/how-to-guides/order-number-customization.md +++ b/16/umbraco-commerce/how-to-guides/order-number-customization.md @@ -4,7 +4,7 @@ description: Learn how to customize the default order number generated in Umbrac # Order Number Customization -Umbraco Commerce provides flexible options for customizing order numbers to meet your business requirements. This guide covers the various approaches from simple template customization to implementing fully custom generators. +Umbraco Commerce provides flexible options for customizing order numbers to meet your business requirements. This guide covers different approaches, from template-based customization to implementing fully custom generators. ## Built-in Generators From b750a6689bb6e726f960541a73dfc4536eb39779 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:26:32 +0200 Subject: [PATCH 03/12] Update 16/umbraco-commerce/how-to-guides/order-number-customization.md --- 16/umbraco-commerce/how-to-guides/order-number-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/how-to-guides/order-number-customization.md b/16/umbraco-commerce/how-to-guides/order-number-customization.md index 8adaeacf679..b6277b85645 100644 --- a/16/umbraco-commerce/how-to-guides/order-number-customization.md +++ b/16/umbraco-commerce/how-to-guides/order-number-customization.md @@ -10,7 +10,7 @@ Umbraco Commerce provides flexible options for customizing order numbers to meet Before implementing a custom solution, understand that Umbraco Commerce includes two built-in order number generators: -- **CompactSortableOrderNumberGenerator** (Recommended) - Produces compact, time-sortable identifiers with excellent scalability and multi-node support +- **CompactSortableOrderNumberGenerator** (Recommended) - Produces compact, time-sortable identifiers with high scalability and multi-node support - **DateHashOrderNumberGenerator** (Legacy) - Date-based format maintained for backward compatibility For detailed information about these generators and how they work, see the [Order Number Generators](../key-concepts/order-number-generators.md) key concepts documentation. From 1a8d5d31efd2eba8dc238e77dedab043a71de81f Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:26:46 +0200 Subject: [PATCH 04/12] Update 16/umbraco-commerce/how-to-guides/order-number-customization.md --- 16/umbraco-commerce/how-to-guides/order-number-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/how-to-guides/order-number-customization.md b/16/umbraco-commerce/how-to-guides/order-number-customization.md index b6277b85645..7b9eca7dbbc 100644 --- a/16/umbraco-commerce/how-to-guides/order-number-customization.md +++ b/16/umbraco-commerce/how-to-guides/order-number-customization.md @@ -17,7 +17,7 @@ For detailed information about these generators and how they work, see the [Orde ## Before Creating a Custom Generator -Consider these simpler alternatives before implementing a custom generator: +Consider these alternatives before implementing a custom generator: ### 1. Using Store Templates From e3577cffcabab6002168ffd69ad3f684b6ddee81 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:26:53 +0200 Subject: [PATCH 05/12] Update 16/umbraco-commerce/how-to-guides/order-number-customization.md --- 16/umbraco-commerce/how-to-guides/order-number-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/how-to-guides/order-number-customization.md b/16/umbraco-commerce/how-to-guides/order-number-customization.md index 7b9eca7dbbc..af284566618 100644 --- a/16/umbraco-commerce/how-to-guides/order-number-customization.md +++ b/16/umbraco-commerce/how-to-guides/order-number-customization.md @@ -21,7 +21,7 @@ Consider these alternatives before implementing a custom generator: ### 1. Using Store Templates -The simplest way to customize order numbers is through store-level templates. Templates allow you to add prefixes, suffixes, or formatting without writing any code: +You can customize order numbers through store-level templates. Templates allow you to add prefixes, suffixes, or formatting without writing any code: ```csharp // Configure templates via the Store entity From f44ed6f63f962c2820d1b0c15db26d8c7c2f69e5 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:01 +0200 Subject: [PATCH 06/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index 6a16a649803..a3e4dae18e5 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -1,6 +1,6 @@ --- title: Order Number Generators -description: Documentation for IOrderNumberGenerator in Umbraco Commerce +description: Learn about the `IOrderNumberGenerator` interface in Umbraco Commerce --- # Order Number Generators From d6cf5c19abef6a6189b5498ac7b93109ae8bc39a Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:11 +0200 Subject: [PATCH 07/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index a3e4dae18e5..84480230ee0 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -32,7 +32,7 @@ Umbraco Commerce includes two built-in order number generators: ### CompactSortableOrderNumberGenerator (Recommended) -The `CompactSortableOrderNumberGenerator` is the recommended generator introduced in Umbraco Commerce 16.4. It produces compact, time-sortable identifiers with excellent scalability characteristics. +The `CompactSortableOrderNumberGenerator` is the recommended generator introduced in Umbraco Commerce 16.4. It produces compact, time-sortable identifiers with high scalability characteristics. **Format:** 10-character Base32 encoded ID with hyphen formatting From dfb071a51c4c55bb07ea0511e99784bf77c963cb Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:18 +0200 Subject: [PATCH 08/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index 84480230ee0..01c3bf519ad 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -37,9 +37,9 @@ The `CompactSortableOrderNumberGenerator` is the recommended generator introduce **Format:** 10-character Base32 encoded ID with hyphen formatting Where: -- **timeComponent** - 7 Base32 characters encoding seconds since January 1, 2025 (supports ~1089 years) -- **nodeId** - 1 Base32 character representing the server/node ID (0-31) -- **sequence** - 2 Base32 characters encoding a per-second sequence number (0-1023) +- `timeComponent` - 7 Base32 characters encoding seconds since January 1, 2025 (supports ~1089 years) +- `nodeId` - 1 Base32 character representing the server/node ID (0-31) +- `sequence` - 2 Base32 characters encoding a per-second sequence number (0-1023) **Example:** `22345-67ABC` (hyphen inserted at position 5 for readability) From 347867f1eb4e4b46bc31dfbab8d0bffc31b12293 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:26 +0200 Subject: [PATCH 09/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index 01c3bf519ad..5f95c122d31 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -60,7 +60,7 @@ Cart and order numbers can be formatted using the store's `CartNumberTemplate` a The `DateHashOrderNumberGenerator` is the legacy generator from earlier versions of Umbraco Commerce. It creates order numbers based on the current date and time, combined with a random string component. {% hint style="info" %} -**Note:** This generator is maintained for backward compatibility with existing stores but will eventually be obsoleted. New implementations should use `CompactSortableOrderNumberGenerator`. +This generator is maintained for backward compatibility with existing stores, but will eventually be deprecated. New implementations should use `CompactSortableOrderNumberGenerator`. {% endhint %} **Format:** `{dayCount:00000}-{timeCount:000000}-{randomString}` From 2cc6d24c880f8bd03d97e6d98af950697315b7cf Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:33 +0200 Subject: [PATCH 10/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index 5f95c122d31..ea1c0ffdbe5 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -66,9 +66,9 @@ This generator is maintained for backward compatibility with existing stores, bu **Format:** `{dayCount:00000}-{timeCount:000000}-{randomString}` Where: -- **dayCount** - Number of days since January 1, 2020 (5 digits) -- **timeCount** - Number of seconds elapsed in the current day (6 digits for carts, 5 for orders) -- **randomString** - 5 random characters from the set `BCDFGHJKLMNPQRSTVWXYZ3456789` +- `dayCount` - Number of days since January 1, 2020 (5 digits) +- `timeCount` - Number of seconds elapsed in the current day (6 digits for carts, 5 for orders) +- `randomString` - 5 random characters from the set `BCDFGHJKLMNPQRSTVWXYZ3456789` **Example:** `02103-45678-H4K9P` From 21d6cde7b150b4e5f49d44327fcbee4f6043d6b0 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:40 +0200 Subject: [PATCH 11/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index ea1c0ffdbe5..ae56eb5c219 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -124,7 +124,7 @@ public class MyComposer : IComposer ``` {% hint style="warning" %} -**Warning:** Changing the order number generator on an existing store will result in different number formats for new orders. Ensure your business processes and integrations can handle mixed formats before making changes. +Changing the order number generator on an existing store will result in different number formats for new orders. Ensure your business processes and integrations can handle mixed formats before making changes. {% endhint %} ## Creating a Custom Generator From 75dbf4133806f3375c6c912c8f484b0538be1d4f Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:27:47 +0200 Subject: [PATCH 12/12] Update 16/umbraco-commerce/key-concepts/order-number-generators.md --- 16/umbraco-commerce/key-concepts/order-number-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-commerce/key-concepts/order-number-generators.md b/16/umbraco-commerce/key-concepts/order-number-generators.md index ae56eb5c219..4dc99d4b708 100644 --- a/16/umbraco-commerce/key-concepts/order-number-generators.md +++ b/16/umbraco-commerce/key-concepts/order-number-generators.md @@ -194,7 +194,7 @@ When implementing a custom generator, ensure: 8. **Readability** - Balance uniqueness with human readability for customer communication {% hint style="warning" %} -**Important:** Order numbers may have gaps if customers cancel or modify orders during the checkout process. Umbraco Commerce is not designed as an accounting platform. If you require strict sequential numbering for accounting purposes, integration with a dedicated accounting system is recommended. Additionally, sequential numbering can impact performance due to potential database access requirements. + Order numbers may have gaps if customers cancel or modify orders during the checkout process. Umbraco Commerce is not designed as an accounting platform. If you require strict sequential numbering for accounting purposes, integration with a dedicated accounting system is recommended. Additionally, sequential numbering can impact performance due to potential database access requirements. {% endhint %} ## Configuration