Allow order reference number to be unique

[lukeholder]

Currently the order reference is not validated as unique as the order number is used for most handling of the order. It also allows for orders to complete even if an order reference number format accidentally made a duplicate reference without breaking checkout.

We should possibly look to make an option to validate uniqueness, or treat them like slugs with a -2 on the end.

[mgambella]

Yes, @lukeholder — this would be a very welcome improvement!

The expectation is that duplicate order reference numbers should not be allowed under any circumstances — whether they're created or modified via the Control Panel, programmatically in PHP, or through the Ajax APIs.

I’d also suggest that the uniqueness enforcement should be stricter than how slugs are currently handled. Automatically appending something like -2 may not align with accounting or business rule systems that rely on strict reference formats. Ideally, the behavior for handling collisions should either be configurable or disabled entirely, allowing developers to define a format that suits their use case.

[lukeholder]

@mgambella what would you expect if an order comes in and a reference needs to be generated but the order reference format generates a duplicate reference string? We cant error out as the order needs to be completed.

[mgambella]

@lukeholder I understand that orders cannot be errored out since they have to be completed, perhaps for this edge cases we would expect some extra sequential number appended like /1 /2 /3 .. or -1, -2, -3 ... or _1, _2, _3 ...
Possibly, the sequential number should start from 1 and not from 2 like slugs (or it should be configurable) and the separation character should be configurable too, so that this would allow maximum flexibility for business rules.

[mgambella]

furthermore, it would be great if also the format of the reference number would be enforced to have the same structure across all the orders

[lukeholder]

The format is only used at order completion, you will need to update the previous orders either manually or by using the resave command: https://craftcms.com/knowledge-base/bulk-resaving-elements

You would need to use the arrow function method in the cli re-save to set the reference to something like this:

php craft resave/orders --set reference --to "fn(\$order) => \\Craft::\$app->getView()->renderObjectTemplate(\$order->getStore()->getOrderReferenceFormat(), \$order)"

I haven't tested the above but something like that should work. Please test it in development with a backup before proceeding.