> 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/commands/syncing-oms-state-transitions-to-omnitron.md).

# Syncing OMS State Transitions to Omnitron

When a package or transfer order moves from one state to another in OMS (for example, packaging is completed, the package is shipped, or it is delivered), that change can be reflected on the related order items in Omnitron. Whether this happens is controlled by the `sync_remote_order_status` key in the `configuration` field of the relevant **state transition**.

In this tutorial, you will learn how the key works, which commands read it, and how to configure it from the Omnitron UI or through the API.

### What You Will Learn

* How `sync_remote_order_status` affects OMS–Omnitron synchronization
* Where to define the key for a state transition
* Which commands read the key and what each one sends to Omnitron
* How to configure the key safely without losing existing settings

### Prerequisites

* Access to Omnitron with the `state-transitions-create-v2` permission (StateTransitionManage Update) to edit state transitions from the UI. Partner users with this permission can make the change themselves.
* API access to the OMS endpoints if you plan to configure transitions through the API.
* The command slug of the state transition you want to configure (for example, `COMPLETE_PACKAGING`).

### How the Key Works

| Value       | Behavior                                                                                                                                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`      | During the transition, OMS updates the status of the order items in Omnitron. Depending on the command, it can also update fields such as the shipping company, tracking number, and invoice information. |
| `false`     | OMS performs the transition on its own side and **sends nothing to Omnitron**.                                                                                                                            |
| Not defined | The behavior depends on the command. See the **Default** column in Step 2. For some commands, the default is `false`, so synchronization **never runs** unless the key is set explicitly.                 |

The configuration is **per transition**. Two different transitions that use the same command can have different values.

### Step 1: Locate the State Transition

Each state transition has a JSON `configuration` field. `sync_remote_order_status` is a boolean key inside this JSON.

#### Option A: From the Omnitron UI

1. In Omnitron, go to the OMS settings and open the **State Transitions** management screen.
2. Find and open the transition you want to configure.
3. Locate the configuration JSON. You will add or edit the key here in Step 3.

#### Option B: From the API

Use the following endpoints:

| Operation                    | Endpoint                                                           |
| ---------------------------- | ------------------------------------------------------------------ |
| List transitions             | `GET /api/v1/oms/state-transitions-manage/?command=<COMMAND_SLUG>` |
| Retrieve a single transition | `GET /api/v1/oms/state-transitions-manage/<id>/`                   |
| Update the configuration     | `PATCH /api/v1/oms/state-transitions-manage/<id>/`                 |

The list endpoint can be filtered by `command`, `slug`, `source_state`, `destination_state`, and `label`.

1. List the transitions for your command and note the `id` of the transition you want to configure:

```
   GET /api/v1/oms/state-transitions-manage/?command=COMPLETE_PACKAGING
```

2. Retrieve the transition and copy its current `configuration` value:

```
   GET /api/v1/oms/state-transitions-manage/<id>/
```

### Step 2: Check How Your Command Handles the Key

Before you change the configuration, check whether your command reads the key, what its default value is, and what it sends to Omnitron.

#### Package Commands

| Command (`command`)                     | Default | Sent to Omnitron when `true`                                                          |
| --------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `PKG_STATE_TRANSITION`                  | `false` | Item status `450` (preparing)                                                         |
| `PKG_DEALLOCATE_RESERVATIONS`           | `true`  | Item status `450` (preparing)                                                         |
| `COMPLETE_PACKAGING`                    | `true`  | Status, serial number, invoice number and e-archive URL, cash-on-delivery item if any |
| `CHANNEL_BASED_COMPLETE_PACKAGING`      | `true`  | Status `450`, serial number, defined shipping information                             |
| `COMPLETE_PACKAGING_WITHOUT_SHIPMENT`   | `true`  | Status `450`, serial number, cash-on-delivery item                                    |
| `SHIP_THE_PACKAGE`                      | `true`  | Shipping company, tracking number, status, invoice information                        |
| `SHIP_THE_PACKAGE_ADVANCED`             | `true`  | Shipping company, tracking number, status, invoice information                        |
| `SHIP_THE_PACKAGE_BASIC`                | `true`  | Shipping company; status `500` (shipped) if a tracking number exists\*                |
| `READY_FOR_PICKUP`                      | `true`  | Status `520` (ready for pickup), invoice information                                  |
| `SELF_SERVICE_PACKAGE_DELIVERY_COMMAND` | `true`  | Status `550` (delivered)                                                              |
| `UPDATE_PACKAGE_SHIPMENT_STATUS`        | `true`  | Status `550` (delivered) or `540` (attempted delivery)                                |
| `PACKED_FOR_REFUND`                     | `true`  | Refund packaging item information                                                     |

\* For `SHIP_THE_PACKAGE_BASIC`, if you want the status to be sent even without a tracking number, also define `"sync_omnitron_status_without_tracking_number": true`.

#### Transfer Order Commands

| Command (`command`)                    | Default | Sent to Omnitron when `true`             |
| -------------------------------------- | ------- | ---------------------------------------- |
| `PREPARE_TRANSFER_ORDER`               | `false` | Item external status `in_transit`        |
| `SHIP_SELECTED_TRANSFER_ORDERS`        | `false` | Item external status `in_transit`        |
| `READY_TO_SHIP_TRANSFER_ORDER`         | `false` | Invoice number and e-archive URL         |
| `READY_TO_SHIP_TRANSFER_ORDER_ADVANCE` | `false` | Shipping company and carrier information |

#### Additional Effect: Omnitron Status Check

When the key is `true`, the `COMPLETE_PACKAGING`, `COMPLETE_PACKAGING_WITHOUT_SHIPMENT`, `SHIP_THE_PACKAGE`, and `SHIP_THE_PACKAGE_BASIC` commands fetch the order items from Omnitron before processing. If the Omnitron status of any item in the package is outside the `350`–`510` range (for example, the item was cancelled in Omnitron), the command returns an error and the transition does not happen.

When the key is `false`, this check is also skipped.

### Step 3: Configure the Key

Add `sync_remote_order_status` to the transition's configuration JSON, or correct its value if it is already defined.

#### From the Omnitron UI

Add the key to the configuration JSON of the transition you opened in Step 1, keeping all existing keys, and save.

#### From the API

> **Warning:** `PATCH` does not merge the `configuration` field; it replaces it entirely. Sending only `{"configuration": {"sync_remote_order_status": true}}` deletes all other keys defined on the transition (such as `send_webhook`, `create_shipment`, and `remote_bill_fulfillment_call`).

To update the configuration safely:

1. Take the current `configuration` you retrieved with `GET` in Step 1.
2. Add or update the `sync_remote_order_status` key.
3. Send the **entire** JSON back:

```
   PATCH /api/v1/oms/state-transitions-manage/<id>/
```

json

```json
   {
     "configuration": {
       "sync_remote_order_status": true,
       "remote_bill_fulfillment_call": true,
       "update_remote_orderitem_invoice": true,
       "send_webhook": true
     }
   }
```

### Step 4: Verify the Configuration

1. Retrieve the transition again and confirm that the key is present and that no existing keys were lost:

```
   GET /api/v1/oms/state-transitions-manage/<id>/
```

2. Trigger the transition on a test package or transfer order.
3. Check the related order items in Omnitron and confirm that the fields listed for your command in Step 2 were updated.

### Configuration Examples

> In the examples below, keys other than `sync_remote_order_status` are illustrative. Keep the keys already defined on your transition and only add or correct `sync_remote_order_status`.

#### Completing Packaging (`COMPLETE_PACKAGING`)

json

```json
{
  "sync_remote_order_status": true,
  "remote_bill_fulfillment_call": true,
  "update_remote_orderitem_invoice": true,
  "send_webhook": true
}
```

#### Shipping Without Waiting for a Tracking Number (`SHIP_THE_PACKAGE_BASIC`)

json

```json
{
  "sync_remote_order_status": true,
  "sync_omnitron_status_without_tracking_number": true
}
```

#### Moving a Package to the Preparing Status (`PKG_STATE_TRANSITION`)

The default for this command is `false`, so the key **must** be defined explicitly:

json

```json
{
  "sync_remote_order_status": true
}
```

#### Preparing a Transfer Order (`PREPARE_TRANSFER_ORDER`)

json

```json
{
  "sync_remote_order_status": true
}
```

#### Intentionally Disabling the Sync

If another integration (for example, an ERP) writes the status to Omnitron, disable the sync to prevent duplicate updates:

json

```json
{
  "sync_remote_order_status": false
}
```

### Troubleshooting

| Symptom                                                       | Possible Cause                                                                       | Solution                                                              |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| The transition completes in OMS, but Omnitron is not updated. | The key is `false`, or it is not defined on a command whose default is `false`.      | Set `"sync_remote_order_status": true` explicitly on the transition.  |
| Other configuration keys disappeared after an update.         | The configuration was updated with a partial `PATCH` body.                           | Restore the missing keys and always send the full configuration JSON. |
| The command fails with an error before the transition.        | An item's Omnitron status is outside the `350`–`510` range (for example, cancelled). | Check the item statuses in Omnitron before retrying the transition.   |
| `SHIP_THE_PACKAGE_BASIC` does not update the status.          | The package has no tracking number.                                                  | Add `"sync_omnitron_status_without_tracking_number": true`.           |
| Order item statuses are updated twice.                        | Both OMS and another integration write the status to Omnitron.                       |                                                                       |


---

# 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/commands/syncing-oms-state-transitions-to-omnitron.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.
