Product Not Found & Wrong Product Command

This document outlines the process for handling "Product Not Found" and "Wrong Product" scenarios within the Akinon Order Management System (OMS). These situations occur when certain products in a packaging order are unavailable or incorrect at the designated stock location, impacting the fulfillment process.

The document details the key actors, domain objects, and the step-by-step process that OMS follows to manage such incidents. It also explains the command parameters used to transition packaging orders to an appropriate status (e.g., "Out of Stock") and describes how quota values are adjusted based on the availability of items in different stock locations.

Additionally, this document provides a detailed API reference for running the POST command, allowing integrated applications to notify OMS about unavailable products in packaging orders. It includes request examples, command parameters, and response formats, ensuring seamless communication and workflow adjustments when products are not found or incorrect.

Actors​

• Akinon Order Management System (OMS)

• Integrated Application (ERP)

Domain Objects​

• Packaging Order

• OMS Command (Packaging Order Command)

Process​

1. The OMS application copies orders from the Akinon Omnitron Application to itself to prepare delivery/distribution plans, generate packaging orders and transfer them to operation points.

2. The products in the order are distributed to the Packaging Orders by running the rules in the distribution scenarios designated by the brand.

3. Packaging Orders are transferred to the Akinon Instore App or the brand’s integrated software. (Packaging Orders Webhooks)

4. Packaging orders assigned to the Store/Warehouse commence in the Waiting status.

5. In the event that a particular product in the package is out of stock, the store/warehouse employee informs the OMS that packaging cannot be carried out. The relevant package and its items are moved to the Out of Stock status, and the package items that are suitable for packaging are rescheduled to create new packages.

6. The DetectedOutOfStockItemCommand is run for a packaging order in the Waiting, Preparing and Ready for Packaging status, completing the transition of the Package and its items to the Out of Stock status.

Command Parameters and Prerequisites​

For each packaging order:

Parameter	Parameter Name	Parameter Type	Parameter Description	Requirement
Packaging Order ID	package	integer	Dynamic for each order	Mandatory
Command Transition ID	transition	integer	Prepared and reported during OMS installation	Optional if slug is given
Slug	slug	slug	Unique slug for stste transition	Optional if Command Transition ID is given
Package Item IDs	package_items	list	A list of package item IDs	Mandatory
Denial Reason	denial_reason	integer	Denial reason ID	Optional

This command may only be run for packages in the following states:

• Waiting (enum_value: 100)

• Preparing (enum_value: 200)

• Ready for Packaging (enum_value: 400)

Running the command in other states will trigger a validation error.

Regardless of scenarios, the process of lowering and raising quotas continues, the quota amount continues to increase and decrease on a location basis. However, for these alterations to impact planning, the scenario rules must have the SELECT_BY_QUOTA value.

• The maximum quota value specifies how many packages can be created from the respective location. The quota value is a user-unspecified parameter used for monitoring the maximum quota value and performing increase or decrease operations.

• max_quota - quota = available_quota

• If the available_quota value is 0, no packages can be created. (To encounter this scenario, the SELECT_BY_QUOTA value must be chosen in the scenario rules.)

• For packages with a status below 400 and in the cancellation_waiting state, the quota value increases by 1. (During this stage, when the package is in the waiting state, the quota amount is considered to increase by 1.)

• Upon packaging a package, the quota value decreases by 1. Consequently, the available_quota increases, enhancing the likelihood of packaging from the respective location.

• In the event of a package cancellation, the quota amount decreases by 1 in a similar way.

POST Product Not Found & Wrong Product​

Path: https://{customer_api_url}/api/v1/oms/packages/{package_id}/command/

• Package ID: XXX

• Transition ID: NNN (set after OMS installation)

• Slug: SSS (Unique Slug Value)

Request Body​

{
  "transition": NNN, 
  "slug": SSS,
  "package": XXX,
  "package_items": [1,2,3]
}

Successful Response​

Status Code: 200 OK

After the successful execution of the command, the API returns following responses.

1. If there are package items that are planned at the same location:

{
  "package__id": 123,
  "package__number": "1234567891234567P3",
  "package__stock_location__id": 2,
  "package__stock_location__name": "Test Store",
  "is_same_location": true
}

1. If there are no package items that are planned at the same location, but there are package items planned for another location.

{
  "package__id": 123,
  "package__number": "1234567891234567P3",
  "package__stock_location__id": 2,
  "package__stock_location__name": "Test Store",
  "is_same_location": false
}

1. If there are no package items that are planned at the same location:

{
  "package__id": null,
  "package__number": "",
  "package__stock_location__id": null,
  "package__stock_location__name": ""
}