README

A Magento 2 module that shortens newly generated order numbers by subtracting a fixed offset from the raw order sequence value:

100056789  →  556789
100043549  →  543549

The order sequence table is never touched, so MySQL keeps guaranteeing uniqueness and concurrency safety — only the number that is handed out gets shortened. Existing orders are never renumbered.

Why

Order numbers are reused downstream as job reference / purchase order numbers, where a 9-digit number is cumbersome. The offset is chosen so short numbers land in a range that is free in every consuming system (with the default offset they start with 5).

How it works

Magento asks for an order number in exactly one place — the order sequence returned by Magento\SalesSequence\Model\Manager::getSequence('order', $storeId). The module hooks that single point:

Magento\SalesSequence\Model\Manager::getSequence('order', $storeId)
   └─ after-plugin (Chefsdeal\ShortOrderNumber\Plugin\ShortenOrderSequence)
        └─ Chefsdeal\ShortOrderNumber\Model\ShortSequence  (decorator)
             getNextValue()    → 100043549 → 543549
             getCurrentValue() → 100043549 → 543549

Because every order-creating flow goes through that method, the short number is applied consistently to:

Admin orders (manually created / phone orders)
Marketplace orders imported by M2E Pro (eBay, Amazon, Walmart)
REST/SOAP API orders and any third-party module that saves an order
Quote reserved_order_id (used by payment gateways such as Stripe before the order is placed)

Invoice, shipment and credit memo sequences are not affected — they use different entity types and the plugin ignores them.

Not covered: orders written straight into the database

An external backend that writes sales_order rows directly never calls Magento's sequence manager, so it must shorten the number itself. The ChefsDeal storefront backend (Butterfly) mints its number in Basket::getReservedIncrementId() and applies the same offset via Basket::ORDER_NUMBER_SHORTEN_OFFSET.

⚠️ The two offsets must stay in sync. If you change sales/short_order_number/offset here, change the backend constant in the same release — otherwise the two producers hand out numbers from two different ranges.

Requirements

Magento 2.3.x / 2.4.x (developed against 2.4.7)
PHP 7.4+
MySQL-backed sales_sequence_* tables (Magento default)

Installation

1. Get the code

Via Composer (Packagist) — in the Magento root directory:

composer require cdmanager/magento-short-order-number

Via Composer (directly from GitHub) — if Packagist is not available yet:

composer config repositories.magento-short-order-number vcs https://github.com/cdmanager/magento-short-order-number
composer require cdmanager/magento-short-order-number:dev-main

Manually — if the project does not use Composer for modules:

mkdir -p app/code/Chefsdeal/ShortOrderNumber
git clone https://github.com/cdmanager/magento-short-order-number.git app/code/Chefsdeal/ShortOrderNumber

2. Enable it

bin/magento module:enable Chefsdeal_ShortOrderNumber
bin/magento setup:upgrade
bin/magento setup:di:compile   # production mode only
bin/magento cache:flush

The module adds no database schema — setup:upgrade only registers it. setup:di:compile is required in production mode because the plugin and the generated ShortSequenceFactory are compiled artifacts.

3. Set the offset

Pick the offset before the first order is placed (see Choosing the offset) and confirm the default matches your sequence:

bin/magento config:set sales/short_order_number/offset 99500000
bin/magento config:set sales/short_order_number/enabled 1
bin/magento cache:clean config
bin/magento config:show sales/short_order_number

4. Verify

Create an order in the admin panel, then check that the stored number is short while the sequence keeps counting in the original range:

SELECT increment_id, created_at FROM sales_order ORDER BY entity_id DESC LIMIT 5;
SELECT MAX(sequence_value) FROM sequence_order_1;

Expected: increment_id = MAX(sequence_value) − offset, and the sequence value itself is still 9 digits.

Also verify one order end-to-end after install: order confirmation email, customer account / order lookup, invoice, shipping label and every downstream integration (OMS, ERP, accounting) show the same short number.

Configuration

Stores → Configuration → Sales → Sales → Short Order Numbers

Field	Config path	Default	Meaning
Shorten New Order Numbers	`sales/short_order_number/enabled`	`1`	Master switch. Set to `0` to hand out raw sequence values again.
Offset	`sales/short_order_number/offset`	`99500000`	Subtracted from the raw order sequence value.

Both settings are store-scoped, so a multi-store setup can shorten only selected stores.

Choosing the offset

The offset determines where new numbers start: start = current sequence value − offset. With a sequence at 100.043.548 and an offset of 99.500.000, numbers start at 543.548.

Before going live, confirm the target range is unused in all systems that store the order number (Magento, ERP/OMS, accounting, job references):

-- current sequence position
SELECT MAX(sequence_value) FROM sequence_order_1;

-- must return 0: no historical order in the target range
SELECT COUNT(*) FROM sales_order
WHERE increment_id REGEXP '^[0-9]+$'
  AND CAST(increment_id AS UNSIGNED) BETWEEN 100000 AND 999999;

Short numbers only climb from their starting point, so once the range is verified empty it stays collision-free: reaching the historical 9-digit band again would take ~99M orders. Note that the digit count grows normally — after ~456k orders a 6-digit number starting with 5 becomes a 7-digit number starting with 1.

Safety rules built into the shortening

A sequence value is only shortened when all of these hold; otherwise it is returned untouched:

the value is purely numeric — numbers from prefixed schemes are left alone
the value is at least 100000000 (ShortSequence::LONG_NUMBER_MIN) — legacy short and zero-padded numbers such as 000000007 pass through unchanged
the configured offset is greater than zero and smaller than the value — the result can never be zero or negative

Rollback

bin/magento config:set sales/short_order_number/enabled 0
bin/magento cache:clean config

New orders immediately go back to the raw 9-digit sequence value. Orders already created with a short number keep it and stay searchable — nothing else changes. To remove the module entirely:

bin/magento module:disable Chefsdeal_ShortOrderNumber
composer remove cdmanager/magento-short-order-number
bin/magento setup:upgrade && bin/magento cache:flush

File map

├── registration.php
├── etc/
│   ├── module.xml                          # depends on Magento_Sales, Magento_SalesSequence
│   ├── di.xml                              # plugin on SalesSequence\Model\Manager
│   ├── config.xml                          # default enabled=1, offset=99500000
│   └── adminhtml/system.xml                # admin fields under Sales → Sales
├── Model/
│   ├── Config.php                          # scoped config reader
│   └── ShortSequence.php                   # sequence decorator, offset + safety rules
├── Plugin/
│   └── ShortenOrderSequence.php            # wraps the 'order' sequence only
└── Test/Unit/Model/ShortSequenceTest.php

Tests

vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist vendor/cdmanager/magento-short-order-number/Test/Unit

Notes

Magento's Sequence::DEFAULT_PATTERN is %s%09d%s, i.e. sequence values are zero-padded to nine digits (this is why legacy numbers look like 000000007). The plugin shortens the value after that formatting, so no padding leaks into the short number.
Reseeding sequence_order_1 instead of using an offset was rejected on purpose: it is destructive, cannot be rolled back, and the %09d pattern would render the reseeded value as 000543549.
The module reads its config per store on every sequence request, so enabled/offset changes take effect after a config cache clean without a deploy.

License

GPL-3.0-only — see LICENSE.

cdmanager / magento-short-order-number

Maintainers

Package info

Statistics

Security