---
title: Order numbers
published: 2026-10-12
lastmod: 2026-10-13
url: https://larasell.dev/docs/order-numbers
---

## Table of contents
- [Configuring order numbers](#configuring-order-numbers)
  - [Changing the prefix](#changing-the-prefix)
  - [Changing the suffix](#changing-the-suffix)
  - [Changing the padding](#changing-the-padding)
  - [Disabling the padding](#disabling-the-padding)
  - [Changing the start number](#changing-the-start-number)
- [Creating a custom generator](#creating-a-custom-generator)
  - [Using multiple sequences](#using-multiple-sequences)

# Order numbers

## Configuring order numbers

Larasell uses the
`SequentialOrderNumberGenerator`{href="https://raw.githubusercontent.com/Larasell-dev/larasell/refs/heads/main/src/OrderNumbers/SequentialOrderNumberGenerator.php"}
by default. It generates order numbers from an incrementing sequence.

You can configure it inside `config/larasell.php`.

### Changing the prefix

By default, Larasell uses the `LS-` prefix for each order number.
To change this, add a `prefix` value to the configuration:

```php
use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => SequentialOrderNumberGenerator::class,
      'prefix' => 'SHOP-',
  ],
];
```

Setting a different prefix changes the order number from `LS-000001` to
`SHOP-000001`. Doing so only affects future order numbers. Existing order
numbers stay the same.

### Changing the suffix

You can also change the suffix. This is useful, for example,
when you run multiple stores in different regions and want the order number
to reflect where the order was placed:

```php
use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => SequentialOrderNumberGenerator::class,
      'suffix' => '-EU',
  ],
];
```

The order number then looks like this: `LS-000001-EU`. Changing the suffix
only affects _new_ order numbers. So changing the `suffix` to `-US` would
generate `LS-000002-US`, keep this in mind.

### Changing the padding

By default, each order number has 6 digits, so every order number has the
same length.

To change the length, change the `padding` value in the `config/larasell.php` file:

```php
use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => SequentialOrderNumberGenerator::class,
      'padding' => 4,
  ]
];
```

Now every _new_ order will have 4 digits, like `LS-0001`.

Once you pass 999999, the length increases by one and every
_new_ order number will have 7 digits. All previous order numbers
keep their 6 digit format.

### Disabling the padding

To disable the padding set the `padding` to `null`:

```php
use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => SequentialOrderNumberGenerator::class,
      'padding' => null,
  ]
];
```

Now, each order number has the amount of digits it needs i.e.
`LS-1`, `LS-2`, `LS-10`, `LS-100` and so forth.

### Changing the start number

The first order number starts at `1`, e.g. `LS-000001`. To change the start
number, edit the `start` value in `config/larasell.php`:

```php
use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => SequentialOrderNumberGenerator::class,
      'start' => 1000,
  ],
];
```

When the start number is higher than the last order number, the generator
skips the numbers in between. When the start
number is lower, the sequence continues from the last order number.

## Creating a custom generator

When you outgrow the default generator, replace
it with a custom one.

You might use an external service or Redis to generate order numbers or need
multiple sequences, for example a sequence that resets for the new year.

Create a new generator using the CLI:

```bash
php artisan make:order-number-generator CustomOrderNumberGenerator
```

That command writes the class to `app/OrderNumbers/Generators`. This one takes the
next integer from the single sequence and returns `ORD-1`, then `ORD-2`:

```php
namespace App\OrderNumbers\Generators;

use Larasell\Larasell\Contracts\OrderNumberGenerator;
use Larasell\Larasell\OrderNumbers\SingleOrderNumberSequence;

class CustomOrderNumberGenerator implements OrderNumberGenerator
{
    public function __construct(private readonly SingleOrderNumberSequence $sequence) {}

    public function generate(): string
    {
        $next = $this->sequence->next();

        return 'ORD-'.$next;
    }
}
```

Finally, register that class as the `generator`:

```php
use App\OrderNumbers\Generators\CustomOrderNumberGenerator;

return [
  'order_numbers' => [
      'generator' => CustomOrderNumberGenerator::class,
  ],
];
```

> [!NOTE]
> This new generator ignores `prefix`, `suffix`, and `padding`.
> You have to implement that customisation yourself. `start` still applies, because `SingleOrderNumberSequence`{href="https://raw.githubusercontent.com/Larasell-dev/larasell/refs/heads/main/src/OrderNumbers/SingleOrderNumberSequence.php"} reads it.

### Using multiple sequences

By default, Larasell generates order numbers using a single sequence that
starts at 1 and counts upwards.

Changing the prefix or suffix leaves the counter running. For example, when you
change the suffix from `-2025` to `-2026`, the counter simply continues: the next order number will be
`LS-000456-2026` instead of `LS-000001-2026`.

Some stores need that, though. They need order numbers to start over (yearly reset) or count upwards
independently (separate sequence for each country).

To help with that Larasell provides a `MultipleOrderNumberSequence`{href="https://raw.githubusercontent.com/Larasell-dev/larasell/refs/heads/main/src/OrderNumbers/MultipleOrderNumberSequence.php"} class. Run `php artisan make:order-number-generator YearlyOrderNumberGenerator`, then replace the generated method so each year has its own sequence:

```php
namespace App\OrderNumbers\Generators;

use Illuminate\Support\Str;
use Larasell\Larasell\Contracts\OrderNumberGenerator;
use Larasell\Larasell\OrderNumbers\MultipleOrderNumberSequence;

class YearlyOrderNumberGenerator implements OrderNumberGenerator
{
    public function __construct(private readonly MultipleOrderNumberSequence $sequences) {}

    public function generate(): string
    {
        $year = now()->format('Y');

        $next = $this->sequences->next('year-'.$year);

        return 'ORD-'.$year.'-'.Str::padLeft($next, 6, '0'); // e.g. ORD-2026-000001
    }
}
```

Larasell stores each sequence by name, so a new name like `year-2026` starts counting from the beginning again.