> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/oms/package-management/package-splitting-rules.md).

# Package Splitting Rules

OMS splits an order into multiple packages based on carrier, stock location, product groups, trade-in items, and stock availability. There is no quantity-, weight-, or volume-based split rule, and no channel-level limit on the number of packages.

This guide explains why and how OMS splits an order, and how split packages are numbered and which status they start in. Splitting is triggered by the packaging rules and the default multiple-packages status configured in [Scenarios](https://docs.akinon.com/technical-guides/oms/scenarios). For step-by-step scenario setup, see [Packaging Scenario Configuration](https://docs.akinon.com/tutorials/oms/packaging-scenario-configuration).

## <mark style="color:red;">Quick Reference</mark>

| Question                                        | Answer                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| When does OMS split a package automatically?    | When order items are planned to different stock locations, belong to different carriers, match a product group (`group_attributes`) defined in the rule, include trade-in products, or are partly out of stock.                                                                                                           |
| Can a maximum package count be set per channel? | No. Scenarios, rules, and application settings have no such field. The channel only determines which scenario, and therefore which rules, runs.                                                                                                                                                                           |
| What is the default behavior?                   | No upper limit. The package count equals the number of distinct (location, product group) pairs in the plan, calculated separately for each carrier group. An out-of-stock package is added for unfulfilled items. See [Channel-Based Maximum Package Count](#channel-based-maximum-package-count) for ways to reduce it. |
| How are split packages numbered?                | With the default generator: `<OrderNumber>P<n>`, where `n` is the total number of the order's packages, including cancelled ones, plus 1.                                                                                                                                                                                 |
| Which status do split packages start in?        | `Waiting (100)` by default. If the scenario defines `default_state_for_multiple_packages` (usually `Waiting Remote Action (150)` in marketplace flows), split packages start in that status. Packages that need a transfer start in `Waiting Transfer Operation (300)`.                                                   |

## <mark style="color:red;">Key Concepts</mark>

| Term                                     | Description                                                                                                                                                                                                                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Packaging scenario (`PackagingScenario`) | Defines which rules are applied to an order and in which order. A scenario is selected by channel, carrier, payment type, segment, client type, `extra_field`, and schedule conditions. Among the matching active scenarios, the one with the lowest `priority` value that can run at that moment wins. |
| Packaging rule (`PackagingRule`)         | Defines which items are packaged (preconditions, product matching), from which locations (location selection and sorting methods), and with which algorithm.                                                                                                                                            |
| Packing plan                             | The intermediate result that assigns each order item to a stock location. Packages are created from this plan.                                                                                                                                                                                          |
| Order execution plan                     | The record that stores the packing plan and the transfer plan. Packages and transfers are created from its plan items.                                                                                                                                                                                  |

In Omnitron, each order item represents a single unit; an order for 3 units of a product arrives as 3 separate items. As a result, units of the same product can be assigned to different locations and end up in different packages.

## <mark style="color:red;">When OMS Splits a Package</mark>

Planning runs in the `fulfil_order` Celery task, which is triggered by the `fulfil_waiting_orders` and `fulfil_replaning_orders` periodic tasks. Each of the criteria below can cause an order to be split into multiple packages.

### <mark style="color:red;">Carrier</mark>

`fulfil_order` first groups the items to be planned by carrier and runs planning separately for each group. If an item has no carrier, the order's carrier is used. Items with different carriers never end up in the same package. Each group selects its own scenario, and the split webhook (see [Split Flag and Webhook](#split-flag-and-webhook)) is evaluated per group.

### <mark style="color:red;">Stock Location</mark>

Packages are created from the plan by the (stock location, product group) key. Items assigned to the same location within a plan are combined into one package; different locations mean different packages. Only locations with `is_fulfillment_center=True` and locations with stock information are considered as candidates during planning.

The rule's algorithm determines how items are distributed across locations:

| Rule setting                                                       | Algorithm         | Effect on package count                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow_partial_packing = false`                                    | Single packing    | The first location that can fulfill all of the rule's items is selected, and all items go into one package. If no single location is sufficient, the rule produces no plan and the next rule is tried. If `allow_transfer_orders = true`, the first location that fulfills the most items is selected and missing items are completed by transfer; this still results in one package. |
| `allow_partial_packing = true`                                     | Partial packing   | Each item is assigned to the first location with stock, based on the sorting. Because items can land in different locations one by one, this mode can produce the most packages.                                                                                                                                                                                                      |
| `allow_partial_packing = true` and `minimize_package_count = true` | Minimize packages | Searches for the smallest set of locations that fulfills the order. Sorting methods do not change the package count; they only break ties. The search is limited to 50 candidate locations, solutions of up to 6 packages, and a budget of about 0.1 seconds. If a limit is exceeded, the result is best effort: valid, but not proven to be minimal. Log tag: `[MIN_PACK]`.          |
| Order is Click & Collect                                           | Click & Collect   | All items are planned into one package at the order's store (`retail_store`).                                                                                                                                                                                                                                                                                                         |
| `PREDEFINED_PACKAGE_LOCATIONS` setting is enabled                  | Predefined        | The location comes from the item's `stock_list.code` value. All items must point to the same location; otherwise, planning fails. One package.                                                                                                                                                                                                                                        |

If a location selection method has a `quota`, a location whose quota is full is no longer a candidate. This can push items to other locations and therefore into new packages.

### <mark style="color:red;">Multiple Rules in a Scenario</mark>

The scenario's rules are tried in priority order. Each rule creates a sub-plan for the items that pass its preconditions. The sub-plans are combined, and planning stops once the order is fully fulfilled. Different rules selecting different locations also cause splits. If a rule with `allow_partial_packing = false` cannot fulfill all of its items, its sub-plan is discarded.

### <mark style="color:red;">Product Group (</mark><mark style="color:red;">`group_attributes`</mark><mark style="color:red;">)</mark>

If `group_attributes` is defined in the rule (for example, `[{"color": "red"}]`), items whose product attributes match a group are placed in a separate package, even if they are at the same location. A group must be fulfilled entirely from a single location. Items that do not match any group are assigned one by one, as in partial packing.

### <mark style="color:red;">Trade-In</mark>

If `IS_TRADEIN_ENABLED` is enabled and an item was planned by a rule with a trade-in product matching method, trade-in items are placed in a separate package from regular items at the same location.

### <mark style="color:red;">Insufficient Stock</mark>

A separate out-of-stock package (`Contains Out-of-Stock Products (920)`) is created for items the plan cannot fulfill. If no item can be fulfilled, the order moves to `failed_fulfillment` status. In this case, an out-of-stock package is created only for items that have never been packaged before, or when the `FORCE_NEW_OOS_PACKAGE` setting is enabled.

### <mark style="color:red;">Splits After Package Creation</mark>

A package can also be split after it is created. In these flows, the source package is cancelled, its items are planned into new packages, and the source package's `number` and `id` are written to the new packages' `extra_information.parent_package` field.

* **Manual assignment** (`ASSIGN_PACKAGE_ITEMS_MANUALLY` command): The user divides the package items into location groups. Each group becomes a separate package. The source package is `cancelled` with the cancellation reason `manual_replan`.
* **Renewing the package plan** (`RenewPackagePlanCommand`) **and out-of-stock detection commands**: Missing items are replanned, and the remaining items may fall into a separate package.
* **Partial replanning**: When out-of-stock or `needs_replan` items are replanned by periodic tasks, new packages are created independently of the order's other packages.

## <mark style="color:red;">Channel-Based Maximum Package Count</mark>

A maximum package count per channel cannot be defined. `PackagingScenario`, `PackagingRule`, and the application settings have no field that limits the number of packages, so by default there is no upper limit and the package count results from the criteria in [When OMS Splits a Package](#when-oms-splits-a-package).

The channel affects splitting only through scenario selection. The scenario's `channel_conditions` field (a static channel list or a dynamic query) determines which channels use that scenario. This lets you set up a different rule set, and therefore different splitting behavior, per channel, but not a numeric limit.

The following settings can be used to reduce the number of packages:

| Goal                                         | Setting                                                               | Notes                                                                                                                                                                                                                                                |
| -------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keep the order in a single package           | A rule with `allow_partial_packing = false` in the channel's scenario | If no single location can fulfill all items, the rule is not applied. If transfers are enabled, missing items are brought in by transfer. Carrier and trade-in separation still apply.                                                               |
| Reduce the package count as much as possible | `allow_partial_packing = true` and `minimize_package_count = true`    | Searches for the minimum set of locations. Does not enforce a fixed upper limit.                                                                                                                                                                     |
| Merge packages at the same location          | `MERGE_SAME_LOCATION_PACKAGES = true`                                 | A global setting, not channel-based. After planning, merges the order's packages at the same location that are in `Waiting (100)` status into a single package. See [Merging Packages at the Same Location](#merging-packages-at-the-same-location). |

## <mark style="color:red;">Numbering and Status of Split Packages</mark>

### <mark style="color:red;">Numbering</mark>

Package numbers are derived from the order number. By default, the `<OrderNumber>P<n>` format is used; one of the following formats can be selected per environment instead.

| Number format              | Structure                                                   | Example                      |
| -------------------------- | ----------------------------------------------------------- | ---------------------------- |
| Standard (default)         | `<OrderNumber>P<n>`                                         | `123456789P1`, `123456789P2` |
| Channel-based              | `<OrderNumber>C<ChannelId>P<n>`                             | `123456789C5P1`              |
| Sequential                 | `<OrderNumber><n>`                                          | `1234567891`                 |
| Delivery option-based      | `<OrderNumber><first 2 letters of the delivery option>P<n>` | `123456789ARP1`              |
| Random (no format defined) | 15-digit random number                                      | `482019375610284`            |

Numbering follows these rules:

* `n` is the total number of the order's packages, including cancelled ones, plus 1. Numbers are not reused: if `P1` is split and cancelled, the new packages become `P2` and `P3`.
* If the order's previous packages do not match the selected format (for example, the format was changed later), the new package gets a random number for backward compatibility.
* If the sequential format is selected but the format check setting is not updated accordingly, the second and later packages get random numbers.
* In the delivery option-based format, a package cannot be created if its items have no delivery option information.
* When packages at the same location are merged (see [Merging Packages at the Same Location](#merging-packages-at-the-same-location)), the new package is numbered in the standard `<OrderNumber>P<n>` format, regardless of the selected format.
* Transfer numbers are derived from the package number: `<PackageNumber>T<n>` (`<PackageNumber><n>` in the sequential format).

### <mark style="color:red;">Initial Status</mark>

| Condition                                                                              | Package status                                                             | Package item status                                                                                     |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Default                                                                                | `Waiting (100)`                                                            | `Waiting (100)`                                                                                         |
| `default_state_for_multiple_packages` is defined in the scenario and the plan is split | The status defined in the scenario (usually `Waiting Remote Action (150)`) | `Waiting Remote Action (120)` if the package status is Waiting Remote Action; otherwise `Waiting (100)` |
| The package requires a transfer                                                        | `Waiting Transfer Operation (300)`                                         | `Selected for Transfer (150)` for items coming by transfer                                              |
| Unfulfilled items                                                                      | `Contains Out-of-Stock Products (920)`                                     | —                                                                                                       |

For the scenario, a plan counts as split if either of these conditions is met:

1. The plan uses more than one stock location.
2. The plan uses a single location but does not cover all of the order's items (partial planning, carrier separation, or later replanning).

This check assigns the same status to every package in the plan. All packages of a split order start in Waiting Remote Action, not only the second one.

If a package starts in Waiting or Waiting Transfer Operation, the location's quota is increased by the number of items (log tag: `[QUOTA_INCREASE]`). Packages that start in Waiting Remote Action do not increase the quota.

### <mark style="color:red;">Split Flag and Webhook</mark>

After the packages are created and the transaction is committed:

* `extra_information.split_package = true` is written to every package whose status equals the scenario's `default_state_for_multiple_packages` value.
* One webhook is sent per planning run. If an `order.split_package` webhook is defined for the order's channel with `config.channel_id`, that webhook is sent; otherwise, `order.fulfillment.multiple_packages` is sent. For a payload example, see [Order Split Package Event Webhook](https://docs.akinon.com/technical-guides/oms/webhooks/webhook-examples/order-split-package-event-webhook).

If `default_state_for_multiple_packages` is not defined in the scenario, no split flag is set and these webhooks are not sent. The packages are announced only through the regular package webhooks.

Packages in Waiting Remote Action status wait for the marketplace to approve the split. The marketplace and Omnitron flow, including cancellation plans and item restructuring, is described in [Package Splitting Flow](https://docs.akinon.com/technical-guides/marketplace-dashboard/package-splitting-flow). On the OMS side, the `rerun_plans_for_cancellation_waiting_packages` task retries pending cancellation plans for Cancellation Waiting and Waiting Remote Action packages updated in the last 15 days.

### <mark style="color:red;">Merging Packages at the Same Location</mark>

If `MERGE_SAME_LOCATION_PACKAGES` is enabled, a merge command runs for each new package after planning. If the order has other packages at the same location in `Waiting (100)` status:

1. All of these packages are cancelled with `force_cancel` (reason: `manual_replan`).
2. Their items are combined into a single new package with a new number and `Waiting` status.
3. Reservations are recreated for the new package.

Packages in Waiting Remote Action or any other status are not merged.

## <mark style="color:red;">Related Pages</mark>

* [Scenarios](https://docs.akinon.com/technical-guides/oms/scenarios): Packaging Rules and Default Multiple Packaging Orders Status settings that trigger splitting.
* [Package Management](https://docs.akinon.com/technical-guides/oms/package-management): General package operations in OMS.
* [Packaging Scenario Configuration](https://docs.akinon.com/tutorials/oms/packaging-scenario-configuration): Step-by-step scenario setup.
* [Package Splitting Flow](https://docs.akinon.com/technical-guides/marketplace-dashboard/package-splitting-flow): Marketplace-specific split approval flow.
* [Order Split Package Event Webhook](https://docs.akinon.com/technical-guides/oms/webhooks/webhook-examples/order-split-package-event-webhook): Webhook payload for developers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/oms/package-management/package-splitting-rules.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
