Installation notes

The standard composer require + setup:upgrade + setup:di:compile flow applies. The points below cover what's specific to this module.

Required dependency

This module requires wimakeit/module-core ^3.0. Composer will pull it automatically from the Wimakeit registry as long as the registry is declared in your project's composer.json.

What the installation changes

• One table is created: wimakeit_order_number_counter (one row per document type, counter scope and period).
• Sales tables are not altered. Numbers already issued never change.
• No JavaScript and no static file: setup:static-content:deploy is not needed for this module.

Nothing changes until you type a format

The module is off by default, and every Number Format is empty. An empty format keeps Magento's own numbering for that document, so you can enable the module and give a custom number to invoices only.

bin/magento config:set wimakeit_order_number/general/enabled 1
bin/magento config:set wimakeit_order_number/invoice/format 'INV-{yyyy}-{counter}'
bin/magento cache:clean config

Restart queue consumers after changing a format: settings are read once per process.

ACL permissions

After installation, the following ACL resource is available under System → Permissions → User Roles:

Configuration

Stores → Configuration → Wimakeit → Order Number. Formats and counters can be set at default, website or store view scope.

General

Order

Invoice, Shipment, Credit Memo

Each has the same settings as the order, plus:

Format rules

A format breaking a rule is refused on save, with the reason.

Command line

bin/magento wimakeit:order-number:counter:list
bin/magento wimakeit:order-number:counter:set invoice 341 [--website=6 | --store=7]

counter:set sets the last value issued: the next number takes it plus the step. Changing Counter Start in the admin does not move an existing counter, this command does. Use it to continue the numbering of a previous system.

Migrating from Amasty Custom Order Number

bin/magento wimakeit:order-number:import-amasty --dry-run   # 1. shows what will be copied, writes nothing
bin/magento module:disable Amasty_Number                    # 2. Amasty rewrites the sequence itself
bin/magento wimakeit:order-number:import-amasty             # 3. import
bin/magento wimakeit:order-number:counter:list              # 4. check

• Settings are copied at the scope they were saved at, and Amasty's built-in defaults are written at default scope for the settings never saved.
• Counters keep their last value. A counter whose date cannot be read is placed in the current period: no number can be issued twice, a yearly restart may be missed once.
• A value this module refuses is listed and the command exits with an error: fix it in the admin.
• Not imported: Timezone offset (dates follow the store view's timezone) and Use Separate Connection (not needed). Settings stored in app/etc/config.php or env.php are not read; the command warns when they exist.
• Re-runnable. Amasty's tables are only read; drop them once Amasty is removed.

Worth knowing

• Gapless documents, serialised. An invoice, shipment or credit memo counter stays locked until the document is saved. Mass invoicing runs one save at a time per counter scope.
• Orders behave like Magento's sequence. The order number is reserved on the quote: an abandoned payment leaves a gap.
• Restart and date. With a yearly restart, put {yy} or {yyyy} in the format. Without it the counter runs into numbers already issued: they are skipped, never issued twice, and after 5 skips in a row Magento's own number is used and a critical entry is logged.
• Precedence. When both the website and the store view have a separate counter, the store view's counter is used.
• {rand} is 4 digits. It keeps numbers apart; it is not a secret.
• A numbering failure never blocks the checkout or an invoice: Magento's number is used and the error is logged.

Cron jobs

None.