> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/apps/events.md).

# Events — 購読できるイベント

アプリが `manifest.subscribes` で購読できるイベントの一覧と payload。型は SDK（`@lmile/app-kit/events`）に定義されています。

| イベント                                   | トリガー                                                                    | 状態      |
| -------------------------------------- | ----------------------------------------------------------------------- | ------- |
| `routing_allocation_decided`           | [Routing](/lmile-docs/routing-api/orders.md) のルーティング完了直後                | **配信中** |
| `fulfillment_shipment_status_changed`  | [Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md) の status 更新直後 | 準備中     |
| `fulfillment_source_inventory_changed` | [在庫取込](/lmile-docs/ingestion-api/inventory-levels.md)の成功直後              | 準備中     |

### 型定義 (JSON Schema)

全イベントの型は [`events.schema.json`](https://github.com/falcon0119/inventory-os/tree/main/docs/apps/events/events.schema.json) が正です（SDK の型はここから生成されます）。

* 項目を足すだけの変更では、イベント名は変わりません。handler は**知らない項目を無視**してください
* 互換の無い変更をするときは、`routing_allocation_decided.v2` のように**新しいイベント名**で配信し、旧イベントもしばらく送り続けます

> いずれも [Webhooks](/lmile-docs/webhooks/overview.md) と同じ発火点・同じ粒度です。アプリ向けイベントには明細の `properties`（名入れ等）と配送先住所が**含まれません**（PII 保護。webhook は受け手が自社サーバーのため `properties` を同梱します）。

***

## `routing_allocation_decided` — 引き当て暫定確定

[Routing](/lmile-docs/routing-api/orders.md)（`/api/routing/orders`）でルーティングが完了した直後、**引き当て先ロケーションごとに 1 イベント** + 引き当て不能明細があれば `unallocated` イベントを 1 件配信します（全量在庫不足 = `no_stock` は `unallocated` のみ）。

### ペイロード

```json
{
  "event": "routing_allocation_decided",
  "shop": "example.myshopify.com",
  "routingOrderId": "7a4c9b3e-...",
  "shipmentId": "f2d81c6a-...",
  "externalOrderRef": "#1234",
  "sourceSystem": "shopify",
  "fromLocationId": "054bccb8-...",
  "fromLocationLabel": "二子玉川MFC",
  "allocationStatus": "allocated",
  "tag": null,
  "decidedAt": "2026-06-04T10:00:00.000Z",
  "lines": [
    { "barcode": "4900000000017", "sku": "SKU-1", "productName": "レザーウォレット", "quantity": 1 }
  ]
}
```

### フィールド

| フィールド               | 型              | 説明                                    |
| ------------------- | -------------- | ------------------------------------- |
| `event`             | string         | `routing_allocation_decided` 固定       |
| `shop`              | string         | 店舗ドメイン                                |
| `routingOrderId`    | string         | ルーティング注文 ID                           |
| `shipmentId`        | string \| null | 出荷元ヘッダ ID（`unallocated` イベントは `null`） |
| `externalOrderRef`  | string \| null | 外部注文参照（相関用）                           |
| `sourceSystem`      | string \| null | 注文の取込元                                |
| `fromLocationId`    | string \| null | 引き当て先ロケーション（`unallocated` は `null`）   |
| `fromLocationLabel` | string \| null | 引き当て先の表示名                             |
| `allocationStatus`  | string         | `allocated` \| `unallocated`          |
| `tag`               | string \| null | 注文の tag                               |
| `decidedAt`         | string         | ルーティング判定時刻（ISO 8601）                  |
| `lines`             | array          | 明細（下記）                                |

#### `lines[]`

引き当て時の明細行。明細単位の任意キー/値（`properties`）違いで行が分かれるため、**同一 `barcode` が複数行になる場合があります**（`properties` 自体はイベントに含まれません）。

| フィールド         | 型              | 説明                                           |
| ------------- | -------------- | -------------------------------------------- |
| `barcode`     | string         | 商品バーコード                                      |
| `sku`         | string \| null | SKU（商品マスターから付与）                              |
| `productName` | string \| null | 商品名（商品マスターから付与）                              |
| `quantity`    | number         | 数量                                           |
| `reason`      | string         | `unallocated` イベントのみ。引き当て不能理由（例: `no_stock`） |

### 冪等性

* 同一ルーティング実行内の重複配信はありません（`routingOrderId` × 出荷先 × `decidedAt` で 1 配信に収束）
* 再ルーティング（[Cancel / Update](/lmile-docs/routing-api/cancel-update.md) 等で `decidedAt` が変わる）は**新しいイベント**として配信されます
* 引き当て結果の**絶対状態**を運ぶため、再配信されても最新イベントで冪等に上書きできます

***

## `fulfillment_shipment_status_changed` — 出荷ステータス遷移（準備中）

出荷元（shipment）の出荷ステータスが遷移したときのイベント。型は SDK に定義済みですが、**アプリへの配信はまだ開始されていません**（開始時に [Changelog](/lmile-docs/resources/changelog.md) で告知します）。それまでは [Fulfillment Status Webhook](/lmile-docs/webhooks/fulfillment-status.md) を利用してください。

## `fulfillment_source_inventory_changed` — 出荷元在庫変動（準備中）

出荷元の合算販売可能在庫が barcode 単位で変動したときのイベント。型は SDK に定義済みですが、**アプリへの配信はまだ開始されていません**。それまでは [Source Inventory Webhook](/lmile-docs/webhooks/source-inventory.md) を利用してください。


---

# 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://lmile.gitbook.io/lmile-docs/apps/events.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.