{"openapi":"3.1.0","info":{"title":"Inventory Manager API","version":"0.1.0","description":"Event-sourced inventory service. Commands append events to the journal and fold them into the read model in the same committed write; queries read the projection; consumers follow the event log via replay + SSE."},"paths":{"/items":{"get":{"tags":["items"],"operationId":"items.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false,"example":"widget"},{"name":"tracking","in":"query","schema":{"type":"string"},"required":false},{"name":"kind","in":"query","schema":{"type":"string"},"required":false,"example":"stock,composite"},{"name":"sellable","in":"query","schema":{"$ref":"#/components/schemas/BooleanString"},"required":false},{"name":"sort","in":"query","schema":{"$ref":"#/components/schemas/ItemSortKey"},"required":false,"example":"sku"},{"name":"order","in":"query","schema":{"$ref":"#/components/schemas/SortOrder"},"required":false,"example":"asc"},{"name":"skus","in":"query","schema":{"type":"string","maxLength":4000},"required":false},{"name":"catalogId","in":"query","schema":{"type":"string"},"required":false,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"locationId","in":"query","schema":{"type":"string"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"50"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryGridPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryGridPageEncoded"},"examples":{"contract":{"summary":"items.list","value":{"items":[{"item":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T02:05:00.000Z"},"levels":{"sku":"WIDGET-BLUE","onHand":158,"reserved":10,"available":148,"damaged":2,"awaitingIdentification":0,"inTransit":6,"incoming":24,"backordered":0,"projected":178,"byLocation":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","fulfillable":true,"onHand":140,"reserved":10,"available":130,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","fulfillable":true,"onHand":18,"reserved":0,"available":18,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"asOf":"2026-10-22T05:30:01.000Z"}},{"item":{"id":"itm_019cd545-fa38-7989-b4f0-ed0cdbf68cff","sku":"WIDGET-RED","name":"Widget, red","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000026","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":0,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":0}],"backordered":4,"cost":{"costCents":1250,"source":"set","at":"2026-03-14T06:00:00.000Z"},"createdAt":"2026-03-10T01:04:19.000Z","updatedAt":"2026-10-19T03:55:12.000Z"},"levels":{"sku":"WIDGET-RED","onHand":0,"reserved":0,"available":0,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":0,"backordered":4,"projected":-4,"byLocation":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","fulfillable":true,"onHand":0,"reserved":0,"available":0,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":0}],"asOf":"2026-10-22T05:30:01.000Z"}},{"composite":{"sku":"WIDGET-PAIR","name":"Widget twin pack","productId":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e","productTitle":"Widget twin pack","variantId":"var_019d4cb8-c618-7383-84f4-8228073621c6","components":[{"sku":"WIDGET-BLUE","quantity":1},{"sku":"WIDGET-RED","quantity":1}]},"availability":{"variantId":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","kind":"composite","onHand":0,"available":0,"projected":-4,"components":[{"sku":"WIDGET-BLUE","quantity":1,"available":148,"kits":148},{"sku":"WIDGET-RED","quantity":1,"available":0,"kits":0}],"limitedBy":["WIDGET-RED"]}}],"total":3,"limit":50,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the SKU master, SKU-ascending, each row carrying the item and its derived `levels` (the same shape `GET /items/:sku/stock` returns) — followed by the kits: composite variants, which hold no stock of their own, appear after the stocked rows as `CompositeItemSummary` with their divisible `availability` and recipe, so the grid is the whole sellable master. `kind=composite` narrows to them (and `kind=stock,service` excludes them). The stocked half is paged and counted by the store; the kits fill the tail of the last stocked page, and `total` counts both. (Also returns, so a grid never has to re-derive `available` — which it could not do honestly anyway without knowing which locations are fulfillable). `q` matches SKU (separators ignored, typos forgiven), name or barcode, best first; `tracking` narrows to one identity mode, `kind` to stock or service items, `sellable` to those that may (or may not) be sold, `catalogId` to the SKUs a channel catalog's products list (an admin viewing the master *as* that channel; an unknown catalog is a 404, and an **archived** one lists nothing — it has been withdrawn, and it resolves empty for every reader), `locationId` to the SKUs held at any of those locations, comma-separated (on the shelf, damaged or awaiting identification there, in transit to it, or expected there from an open purchase order — the master as one site sees it; kits hold no stock anywhere, so a location scope lists stocked rows only), `sort`/`order` reorder the page (`sku`, `name`, `tracking`, `kind`, `createdAt`, `updatedAt`; `asc` or `desc` — the derived stock figures are computed after the page is cut, so they cannot order it), and `total` is the count matching the query with `limit`/`offset` ignored — what a pager needs. Omitting `limit` returns every match in one page, which is how the CSV exporter reads the catalogue.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_list_items","title":"Inventory: List items","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["items"],"operationId":"items.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"procure-to-pay":{"summary":"Procure to pay","value":{"id":"itm_01a15891-6c3f-7d19-9a3e-7c1b5d8e2f10","sku":"WIDGET-BLUE","name":"Blue widget, 40mm","stock":[],"createdAt":"2026-08-17T09:00:00.000Z","updatedAt":"2026-08-17T09:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"SkuConflict | SkuNotAllowed | BarcodeConflict | LocationArchived | UnknownAccountCode | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SkuConflictEncoded"},{"$ref":"#/components/schemas/SkuNotAllowedEncoded"},{"$ref":"#/components/schemas/BarcodeConflictEncoded"},{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/UnknownAccountCodeEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Create a new inventory item with its master data, each field defaulted when omitted: a stock item is counted and sellable and posts to the chart's 1400 / 4000 / 5000 (`accounts`, `GET /accounts`); a service is never counted or tracked and opens at quantity 0. Weight and box are sent to the sales channels that publish it. Appends an `inventory.item-created` event. 409 `SkuConflict` if the SKU exists, `SkuNotAllowed` if the tenant's `skuAlphabet` refuses it, `BarcodeConflict` for another SKU's barcode, `UnknownAccountCode` for a code not in the chart. Idempotent on the SKU: a retried create meets 409 `SkuConflict`, never a second item.\n\nRequires `stock:write` or `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryItemEncoded"},"example":{"sku":"WIDGET-BLUE","name":"Blue widget, 40mm","quantity":0}}},"required":true},"x-mcp-tool":{"name":"inventory_create_item","title":"Inventory: Create item","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","products:write"],"x-example-source":{"origin":"workflow","workflow":"procure-to-pay","step":1}}},"/items/{sku}":{"get":{"tags":["items"],"operationId":"items.get","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"items.get","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T02:05:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One SKU from the master by its SKU (any case; it folds to uppercase): name, kind, tracking, costing method, trade codes (`barcodes`, `hsCodes`, `countryOfOrigin`), measurements (`weightGrams`, `packedSize` in millimetres, `ownPackaging`), `orderRules`, account codes, and its stock per location. 404 `ItemNotFound` when the SKU is not stocked. Read-only.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_get_item","title":"Inventory: Get item","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}},"patch":{"tags":["items"],"operationId":"items.update","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"Add a second barcode and correct the packed weight; nothing else changes.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"},{"value":"093000000019","type":"upc"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":250,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T06:12:30.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"ItemUpdateRefused | BarcodeConflict | UnknownAccountCode | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemUpdateRefusedEncoded"},{"$ref":"#/components/schemas/BarcodeConflictEncoded"},{"$ref":"#/components/schemas/UnknownAccountCodeEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Reconfigure a SKU's master data; only the fields present change. Lists are replaced whole (409 `BarcodeConflict` for another SKU's barcode), `null` clears an optional field, `accounts` must be codes in the chart (409 `UnknownAccountCode`), and `tracking` and `costingMethod` change only while the SKU holds and expects no stock. Appends an `inventory.item-updated` event carrying exactly that patch, as the SKU's activity log shows. 409 `ItemUpdateRefused` when the change contradicts the SKU: an identity or costing switch with stock on hand, or a service asked to be counted or tracked. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `stock:write` or `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryItemEncoded"},"example":{"barcodes":[{"value":"9300000000019","type":"gtin"},{"value":"093000000019","type":"upc"}],"weightGrams":250}}},"required":true},"x-mcp-tool":{"name":"inventory_update_item","title":"Inventory: Update item","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","products:write"],"x-example-source":{"origin":"contract"}}},"/barcodes":{"get":{"tags":["items"],"operationId":"items.byBarcode","parameters":[{"name":"value","in":"query","schema":{"$ref":"#/components/schemas/BarcodeValue_1"},"required":true,"example":"9300000000019"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"BarcodeMatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarcodeMatchEncoded"},"examples":{"contract":{"summary":"items.byBarcode","value":{"sku":"WIDGET-BLUE","barcode":{"value":"9300000000019","type":"gtin"}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"BarcodeNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarcodeNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Resolve a scanned barcode (`value`, matched exactly) to the one SKU — item or kit — that carries it; a tenant's barcodes are unique. 404 `BarcodeNotFound` when none does. Read-only.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_find_barcode","title":"Inventory: Find SKU by barcode","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/cost":{"get":{"tags":["items"],"operationId":"items.cost","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"SkuCost","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCostEncoded"},"examples":{"contract":{"summary":"items.cost","value":{"sku":"WIDGET-BLUE","costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | SkuCostNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/SkuCostNotFoundEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A SKU's cost basis — the replacement cost a cost-plus catalog marks up, in the tenant's home currency: the latest receive that carried a home-currency unit cost (`source: receipt`, purchase-order receipts included) or the latest figure set by hand (`set`), whichever came last. A kit's is its components' cost bases × their quantities (`kit`); 404 `SkuCostNotFound` while a SKU (or any of a kit's components) has none. Not the FIFO average, and never posted: valuation is `GET /valuation/:sku`. Read-only.\n\nRequires `catalogs:read` or `financials:read`.","x-mcp-tool":{"name":"catalog_get_cost","title":"Catalog: Get cost","toolset":"pricing","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read","financials:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["items"],"operationId":"items.setCost","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"SkuCost","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCostEncoded"},"examples":{"contract":{"summary":"Set a standard cost of $13.00 by hand.","value":{"sku":"WIDGET-BLUE","costCents":1300,"source":"set","at":"2026-10-22T06:20:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"SkuCostNotSettable | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SkuCostNotSettableEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set a SKU's cost basis by hand — a standard cost, or an import's starting figure — in the tenant's home currency. It stands until the next receive that carries a cost. A kit's cost basis is its components' and cannot be set (409 `SkuCostNotSettable`). Every cost-plus catalog re-derives from it on its next read. Appends `inventory.sku-cost-set`. Idempotent by content: a retry setting the same figure appends nothing.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSkuCostEncoded"},"example":{"costCents":1300}}},"required":true},"x-mcp-tool":{"name":"catalog_set_cost","title":"Catalog: Set cost","toolset":"pricing","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/events":{"get":{"tags":["items"],"operationId":"items.events","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"3"},{"name":"before","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ItemEventPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemEventPageEncoded"},"examples":{"contract":{"summary":"The three latest movements; pass `next` as `before` for older ones.","value":{"events":[{"_tag":"inventory.stock-dispatched","eventId":"evt_01a1615a-c0e0-7d38-a94d-ee5249f39be3","txId":"tx_01a1615a-c0e0-7de2-b618-5b6075c9f4c7","tenantId":"org_019cadd3-7f48-7813-b601-1d0e5ec31353","sequence":1042,"occurredAt":"2026-10-22T02:05:00.000Z","source":"inventory-manager","version":1,"actor":{"_tag":"user","id":"usr_019cadd3-7fc0-792b-bb42-1992ef490f3b"},"correlationId":"req_01a1615a-c0e0-756f-be6c-4dc5e8f50d4d","payload":{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"dsp_309cca80-6f93-1b13-35a3-a6c100d3dd4d"}},{"_tag":"inventory.stock-reserved","eventId":"evt_01a16133-14a0-7763-b106-cd51c90e386a","txId":"tx_01a16133-14a0-78fa-98e9-cc5d88322309","tenantId":"org_019cadd3-7f48-7813-b601-1d0e5ec31353","sequence":1038,"occurredAt":"2026-10-22T01:21:40.000Z","source":"inventory-manager","version":1,"actor":{"_tag":"user","id":"usr_019cadd3-7fc0-792b-bb42-1992ef490f3b"},"correlationId":"req_01a16133-14a0-7df7-9f3a-2602dbf3b93f","payload":{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"alloc:ord_01a1612f-7ea8-705d-b799-e8d57826848d:lin_01a1612f-7ea8-7e3e-a6a9-e5568b62d9f6:loc_019cadd3-8330-7e12-aa44-2cd5f05da74a:2"}},{"_tag":"inventory.stock-received","eventId":"evt_01a16131-99b8-7e3c-9094-0b6e0c28413e","txId":"tx_01a16131-99b8-7768-b562-618c4c0db8ae","tenantId":"org_019cadd3-7f48-7813-b601-1d0e5ec31353","sequence":1031,"occurredAt":"2026-10-22T01:20:03.000Z","source":"inventory-manager","version":1,"actor":{"_tag":"user","id":"usr_019cadd3-7fc0-792b-bb42-1992ef490f3b"},"correlationId":"req_01a16131-99b8-7439-8ed3-c1e91b268188","payload":{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":48,"poId":"po_01a141ef-d880-772d-949d-a2ec6691c9c8","unitCostCents":1250,"fx":{"currency":"AUD","home":"AUD","rate":1,"rateDate":"2026-10-22","source":"same"},"reference":"rcpt_01a16131-8e00-74ae-b2dd-7dfe50fb5464:WIDGET-BLUE"}}],"next":1031}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The SKU's activity log: every journalled event that touched it — its creation, each configuration change, every stock movement, the transfer lines that carried it, and the catalog events that priced or recomposed it — newest first, each with its actor and `occurredAt`. A composite SKU (a kit) has no item but has a log: the events naming the kit itself merged with every component's, since a part moving is what changes what the kit can promise. Paged by sequence, back to the SKU's first event: `limit` is 1–500 (100 when omitted), and a page carries `next` while older events remain — pass it as `before` for the next page. A cursor rather than an offset, so a movement landing mid-read never shifts a page. 404 `ItemNotFound` for a SKU that is neither an item nor a kit of the tenant's.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_item_history","title":"Inventory: Item history","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/incoming":{"get":{"tags":["items"],"operationId":"items.incoming","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"50"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"IncomingPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingPageEncoded"},"examples":{"contract":{"summary":"items.incoming","value":{"items":[{"sku":"WIDGET-BLUE","poId":"po_01a15b5d-3ec0-798a-b36c-61acb91c7c7d","quantity":24,"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","since":"2026-10-20T22:10:00.000Z"}],"total":1,"limit":50,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the purchase orders a SKU is expecting: one row per order and landing site, with the units still to arrive and `since` (when the order first expected them), oldest first. The item and its levels carry only the per-site totals; the orders behind them are read here, a page at a time, because a SKU can be on any number of open orders. `limit` is 1–200, 50 when omitted. 404 `ItemNotFound` for a SKU the tenant does not stock.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_item_incoming","title":"Inventory: Item incoming","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["items"],"operationId":"items.expectIncoming","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"A purchase order is authorised for 24 units landing at Main.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":94,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":72},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-20T22:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Register units expected from a purchase order (the PO system will emit this once built; until then it can be called directly). Accumulates per `poId`; receiving with the same `poId` draws the expectation down. Appends `inventory.incoming-expected`. `reference` is required (purchasing passes `<poId>:<sku>`) and is the idempotency key: a retry with the same reference is acknowledged with the current document and appends nothing.\n\nRequires `purchasing:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpectIncomingEncoded"},"example":{"poId":"po_01a15b5d-3ec0-798a-b36c-61acb91c7c7d","quantity":24,"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","reference":"po_01a15b5d-3ec0-798a-b36c-61acb91c7c7d:WIDGET-BLUE"}}},"required":true},"x-mcp-withheld":"Registered by purchasing when a purchase order is authorised; an agent authorises the PO (`purchasing_authorise_po`) rather than hand-registering what it expects.","x-required-scopes":["purchasing:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/backorders":{"get":{"tags":["items"],"operationId":"items.backorders","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-RED"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"50"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"BackorderPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackorderPageEncoded"},"examples":{"contract":{"summary":"items.backorders","value":{"items":[{"sku":"WIDGET-RED","orderId":"ord_01a1524c-9100-7dd7-8de1-e83eca5bf599","quantity":4,"since":"2026-10-19T03:55:12.000Z"}],"total":1,"limit":50,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the sales orders a SKU is short on, as fulfillment last reported each: the order's current shortfall and `since` (when it first fell short), longest-waiting first. The item's `backordered` is their sum; the orders are read here, a page at a time, because a best-seller out of stock can be short on thousands. Fulfillment's `GET /backorders` is the ranked allocation queue across SKUs. `limit` is 1–200, 50 when omitted. 404 `ItemNotFound` for a SKU the tenant does not stock.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_item_backorders","title":"Inventory: Item backorders","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/adjust":{"post":{"tags":["items"],"operationId":"items.adjust","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"A recount at Main found three fewer than the system held.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":137,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T06:30:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | InsufficientStock | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Adjust stock for an item by a delta with a reason — non-zero, except that a `recount` may carry `0`: a count that matched the shelf moves nothing but still records when the location was last counted (`GET /stock/attention`). Appends an `inventory.stock-adjusted` event; rejected with 409 `InsufficientStock` if the delta would take available stock below zero. `reference` is required and is the idempotency key: a retry with the same reference is acknowledged with the current document and appends nothing.\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","delta":-3,"reason":"recount","reference":"recount-main-2026-10-22-aisle-3"}}},"required":true},"x-mcp-tool":{"name":"inventory_adjust_stock","title":"Inventory: Adjust stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/receive":{"post":{"tags":["items"],"operationId":"items.receive","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"48 units of a purchase order arrive at Main at $12.50 each.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":142,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T01:20:03.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | ReferenceRateUnavailable | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/ReferenceRateUnavailableEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Record that a quantity arrived, at `locationId` or else the default location. An untracked SKU goes into on-hand and can be sold at once. A serial- or batch-tracked SKU's units wait in `awaitingIdentification`, out of `available`, until `POST /items/:sku/identify` names them. An optional `poId` consumes that purchase order's incoming expectation. An optional `unitCostCents` values the units: with no `poId`, accounting opens a cost layer at it. A unit cost in the home currency (`costCurrency` absent or equal to it) also becomes the SKU's cost basis (`GET /items/:sku/cost`); a cost carries that day's exchange rate (409 `ReferenceRateUnavailable` when none). Appends `inventory.stock-received`. `reference` (the document the stock came on: a delivery note, or a receipt id) is required and is the idempotency key: a reference already in the journal is acknowledged without re-applying, and appends nothing.\n\nRequires `receiving:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":48,"poId":"po_01a141ef-d880-772d-949d-a2ec6691c9c8","unitCostCents":1250,"reference":"rcpt_01a16131-8e00-74ae-b2dd-7dfe50fb5464:WIDGET-BLUE"}}},"required":true},"x-mcp-tool":{"name":"inventory_receive_stock","title":"Inventory: Receive stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["receiving:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/damage":{"post":{"tags":["items"],"operationId":"items.damage","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"items.damage","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":138,"reserved":10,"damaged":4,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T03:40:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | InsufficientStock | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Move a quantity from on-hand to damaged (409 `InsufficientStock` if on-hand is short). `reference` is required and is the idempotency key: a retry with the same reference is acknowledged with the current item and appends nothing. For tracked (serial/batch) SKUs the reference must name the document that identified the units — use fulfillment's `POST /write-offs` (disposition `keep-damaged`), which validates the serials/lot against the shelf and issues this command with its write-off id. Appends `inventory.stock-damaged`.\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DamageStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"reference":"damage-main-2026-10-22-crushed-carton"}}},"required":true},"x-mcp-tool":{"name":"inventory_damage_stock","title":"Inventory: Damage stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/dispose":{"post":{"tags":["items"],"operationId":"items.dispose","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"A write-off empties the two damaged units at Main.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T04:11:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | InsufficientStock | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Remove a quantity from the platform for good — the exit path for damaged, expired or lost stock, issued by fulfillment's write-off flow. `bucket: \"onHand\"` (default) takes sellable stock straight out (releasing any reservation the units can no longer honour); `\"damaged\"` empties the damaged bucket (refund returns, kept damage). 409 `InsufficientStock` when the named bucket holds fewer units than requested. Idempotency key: `reference` (the write-off id) — a reference already in the journal is acknowledged without re-applying. Appends `inventory.stock-disposed`.\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisposeStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"bucket":"damaged","reference":"wo_01a161ce-1c20-7dff-a6bc-a874e9206a6b"}}},"required":true},"x-mcp-tool":{"name":"inventory_dispose_stock","title":"Inventory: Dispose stock","toolset":"stock","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/dispatch":{"post":{"tags":["items"],"operationId":"items.dispatch","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"Two units leave Main for a sales order; their hold goes with them.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T02:05:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | InsufficientStock | LocationNotFulfillable | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/LocationNotFulfillableEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Dispatch a quantity out of on-hand — issued by the fulfillment system at ship authorisation (409 `InsufficientStock` if on-hand is short). `orderId` links the movement to the sales order. Appends `inventory.stock-dispatched`. `reference` (the dispatch id) is required and is the idempotency key: a retry with the same reference is acknowledged and appends nothing.\n\nRequires `allocations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispatchStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"dsp_309cca80-6f93-1b13-35a3-a6c100d3dd4d"}}},"required":true},"x-mcp-tool":{"name":"inventory_dispatch_stock","title":"Inventory: Dispatch stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["allocations:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/reserve":{"post":{"tags":["items"],"operationId":"items.reserve","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"Allocation holds two units at Main for one line of a sales order.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":142,"reserved":12,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T01:21:40.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | InsufficientStock | LocationNotFulfillable | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/LocationNotFulfillableEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Hold a quantity for a sales order without moving it — issued by the fulfillment system at allocation. Reserved units stay on-hand and leave `available`, so nothing else can be promised them (409 `InsufficientStock` when `available` is short). Idempotency key: `reference` (typically `alloc:<orderId>:<sku>:<locationId>:<allocated>`, with the component SKU inserted for a kit) — a reference already in the journal is acknowledged without reserving twice. Appends `inventory.stock-reserved`.\n\nRequires `allocations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReserveStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"alloc:ord_01a1612f-7ea8-705d-b799-e8d57826848d:lin_01a1612f-7ea8-7e3e-a6a9-e5568b62d9f6:loc_019cadd3-8330-7e12-aa44-2cd5f05da74a:2"}}},"required":true},"x-mcp-tool":{"name":"inventory_reserve_stock","title":"Inventory: Reserve stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["allocations:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/release":{"post":{"tags":["items"],"operationId":"items.release","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"The order was cancelled: its two-unit hold goes back.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":8,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T04:30:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Give a reservation back — the order was cancelled, split, or re-allocated. Releasing more than is reserved is clamped at zero rather than refused: the reservation counter is a promise, not a physical bucket. Idempotency key: `reference`. Appends `inventory.stock-released`.\n\nRequires `allocations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"release:ord_01a1612f-7ea8-705d-b799-e8d57826848d:lin_01a1612f-7ea8-7e3e-a6a9-e5568b62d9f6:loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"}}},"required":true},"x-mcp-tool":{"name":"inventory_release_stock","title":"Inventory: Release stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["allocations:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/return":{"post":{"tags":["items"],"operationId":"items.return","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"A refund restocks one unit, back on the shelf at Main.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":141,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T05:30:01.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Take units back from a customer — issued by the fulfillment system when a refund restocks. `condition: \"sellable\"` returns them to on-hand; `\"damaged\"` puts them in the damaged bucket, out of sellable stock. Unit/lot identity rides on the fulfillment refund, not here. Idempotency key: `reference` (the refund id). Appends `inventory.stock-returned`.\n\nRequires `allocations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnStockEncoded"},"example":{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":1,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"rfd:rfd_01a16216-6fc0-73d8-842d-645058fea769:0","condition":"sellable"}}},"required":true},"x-mcp-tool":{"name":"inventory_return_stock","title":"Inventory: Return stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["allocations:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/incoming/cancel":{"post":{"tags":["items"],"operationId":"items.cancelIncoming","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"The purchase order is cancelled: its 24 units are no longer expected.","value":{"id":"itm_019cd543-e6f8-7bec-b392-ec0ac6b812ed","sku":"WIDGET-BLUE","name":"Widget, blue","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000019","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":140,"reserved":10,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":0},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","onHand":18,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"backordered":0,"cost":{"costCents":1250,"source":"receipt","at":"2026-10-22T01:20:03.000Z"},"createdAt":"2026-03-10T01:02:03.000Z","updatedAt":"2026-10-22T06:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Stop expecting a purchase order's units for this SKU, at every site at once — issued by purchasing when an order is cancelled, short-closed with its remainder cancelled, or its lines rewritten (the rewrite cancels, then expects the new quantity). Appends `inventory.incoming-cancelled`; an order with nothing expected here appends nothing. `reference` is required and is the idempotency key: a retry with the same reference is acknowledged with the current document and appends nothing.\n\nRequires `purchasing:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelIncomingEncoded"},"example":{"poId":"po_01a15b5d-3ec0-798a-b36c-61acb91c7c7d","reference":"po_01a15b5d-3ec0-798a-b36c-61acb91c7c7d:WIDGET-BLUE:cancel"}}},"required":true},"x-mcp-withheld":"Issued by purchasing when a purchase order is cancelled, short-closed or rewritten; an agent changes the PO (`purchasing_update_po`, `purchasing_cancel_po`, `purchasing_close_po`) instead.","x-required-scopes":["purchasing:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/identify":{"post":{"tags":["items"],"operationId":"items.identify","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-SERIAL"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"Name the two serialised units a receipt left waiting, so they can be sold.","value":{"id":"itm_019dfab1-0b40-7767-ab5a-c0a2dbf90526","sku":"WIDGET-SERIAL","name":"Widget controller, serialised","tracking":"serial","costingMethod":"special-serial","kind":"stock","counted":true,"sellable":true,"barcodes":[],"hsCodes":[],"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":7,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":0}],"backordered":0,"cost":{"costCents":8900,"source":"receipt","at":"2026-10-22T22:41:00.000Z"},"createdAt":"2026-05-06T00:30:00.000Z","updatedAt":"2026-10-22T22:41:02.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | NothingAwaitingIdentification | IdentityTrackingMismatch | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/NothingAwaitingIdentificationEncoded"},{"$ref":"#/components/schemas/IdentityTrackingMismatchEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Name the units that arrived, which is what lets them into the sellable pool: one serial per unit for a serial-tracked SKU, a batch (optionally with an expiry) for a batch-tracked one. Moves the quantity out of `awaitingIdentification` and into on-hand, and appends `inventory.stock-identified` — the event the registry fold reads to put the named units on the shelf. 409 `NothingAwaitingIdentification` if more units are named than have arrived unidentified; 409 `IdentityTrackingMismatch` if the identity does not match the SKU's tracking mode, including any attempt to identify an untracked SKU (whose stock never waits). Idempotency key: `reference`, the receipt id that caused the arrival — purchasing issues this itself straight after its receipt, so a receipt that carries serials never leaves stock in the holding bucket at all. **Note the seam:** the shelf registry (`/shelf/:sku`) still takes its identity from the purchasing receipt, so units identified here without a purchase order behind them reach on-hand but not the shelf. Moving the registry's identity source onto this event is the change that closes it.\n\nRequires `stock:write` or `receiving:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyStockEncoded"},"example":{"quantity":2,"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","serials":["WS-000187","WS-000188"],"reference":"rcpt_01a165c6-5860-7504-9e88-9a2239177d20:WIDGET-SERIAL"}}},"required":true},"x-mcp-tool":{"name":"inventory_identify_stock","title":"Inventory: Identify stock","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","receiving:write"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/shortfall":{"post":{"tags":["items"],"operationId":"items.recordShortfall","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-RED"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"InventoryItem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemEncoded"},"examples":{"contract":{"summary":"Allocation could not cover four units of an order: the SKU is now backordered by four.","value":{"id":"itm_019cd545-fa38-7989-b4f0-ed0cdbf68cff","sku":"WIDGET-RED","name":"Widget, red","tracking":"none","costingMethod":"fifo","kind":"stock","counted":true,"sellable":true,"barcodes":[{"value":"9300000000026","type":"gtin"}],"hsCodes":[{"country":"AU","code":"39269000"}],"countryOfOrigin":"AU","weightGrams":240,"packedSize":{"lengthMm":120,"widthMm":80,"heightMm":60},"ownPackaging":false,"accounts":{"inventory":"1400","revenue":"4000","expense":"5000"},"taxClass":"standard","stock":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","onHand":0,"reserved":0,"damaged":0,"awaitingIdentification":0,"inTransit":0,"incoming":0}],"backordered":4,"cost":{"costCents":1250,"source":"set","at":"2026-03-14T06:00:00.000Z"},"createdAt":"2026-03-10T01:04:19.000Z","updatedAt":"2026-10-19T03:55:12.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Report what a sales order still cannot be given (issued by the fulfillment system after allocation). This is the demand-side twin of `/items/:sku/incoming`: purchasing says what is coming in, fulfillment says what is owed out, and inventory is the one place that can answer whether the two balance. `quantity` is the order's *current* residual shortfall and **replaces** any previous report for that order — 0 clears it. Replacing rather than accumulating is what makes re-allocation safe to run as often as you like. Appends `inventory.shortfall-recorded`. Idempotent by content: a retry reporting the same residual appends nothing.\n\nRequires `allocations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordShortfallEncoded"},"example":{"orderId":"ord_01a1524c-9100-7dd7-8de1-e83eca5bf599","quantity":4}}},"required":true},"x-mcp-tool":{"name":"inventory_record_shortfall","title":"Inventory: Record shortfall","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["allocations:write"],"x-example-source":{"origin":"contract"}}},"/stock/attention":{"get":{"tags":["items"],"operationId":"items.attention","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"StockAttention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockAttentionEncoded"},"examples":{"contract":{"summary":"items.attention","value":{"shortSkus":1,"short":[{"sku":"WIDGET-RED","name":"Widget, red","projected":-4,"available":0,"incoming":0,"backordered":4}],"counts":[{"locationId":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc","name":"Quarantine bay"},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","name":"Shopfront","lastCountedAt":"2026-03-14T09:45:00.000Z"},{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","name":"Main","lastCountedAt":"2026-10-22T06:30:00.000Z"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"What in the stock needs a person — the home dashboard's inventory cards. `shortSkus` counts the stocked SKUs whose `projected` (`available + incoming + inTransit − backordered`, as `GET /items/:sku/stock` reports it) is below zero: more promised than is on hand and on its way, the platform's reorder signal; `short` names the five furthest short. `counts` lists every live location with `lastCountedAt`, the latest `recount` adjustment there (a count that matched the shelf included; absent when the location was never counted), never-counted and longest-since first. Read-only.\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read`.","x-mcp-tool":{"name":"inventory_get_stock_attention","title":"Inventory: Get stock attention","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/stock":{"get":{"tags":["items"],"operationId":"items.stock","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"StockLevels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLevelsEncoded"},"examples":{"contract":{"summary":"items.stock","value":{"sku":"WIDGET-BLUE","onHand":158,"reserved":10,"available":148,"damaged":2,"awaitingIdentification":0,"inTransit":6,"incoming":24,"backordered":0,"projected":178,"byLocation":[{"locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","fulfillable":true,"onHand":140,"reserved":10,"available":130,"damaged":2,"awaitingIdentification":0,"inTransit":0,"incoming":24},{"locationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","fulfillable":true,"onHand":18,"reserved":0,"available":18,"damaged":0,"awaitingIdentification":0,"inTransit":6,"incoming":0}],"asOf":"2026-10-22T05:30:01.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A SKU's stock levels, how many on hand: every quantity bucket as of now, in one read — `onHand`; `reserved` (held for sales orders); `available` (`onHand − reserved`, what a new order can be promised); `damaged`; `awaitingIdentification` (tracked units that have arrived but have not been named, deliberately outside `available`); `incoming` (open purchase-order expectations, registered when a PO is authorised); `backordered` (accepted sales demand this SKU cannot cover, reported by fulfillment at allocation); and `projected` — `available + incoming − backordered`, which goes **negative** when the orders already taken exceed everything on hand and on its way. That negative number is the reorder signal, and the reason all of these live in one shape rather than across three services. Expiry-aware shelf views live with the registry fold (see `/shelf/:sku`).\n\nRequires `stock:read` or `products:read` or `receiving:read` or `purchasing:read` or `allocations:read`.","x-mcp-tool":{"name":"inventory_get_stock","title":"Inventory: Get stock","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read","products:read","receiving:read","purchasing:read","allocations:read"],"x-example-source":{"origin":"contract"}}},"/locations":{"get":{"tags":["locations"],"operationId":"locations.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false},{"name":"archived","in":"query","schema":{"$ref":"#/components/schemas/BooleanString"},"required":false,"example":"false"},{"name":"fulfillable","in":"query","schema":{"$ref":"#/components/schemas/BooleanString"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"LocationPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationPageEncoded"},"examples":{"contract":{"summary":"locations.list","value":{"items":[{"id":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","name":"Main","fulfillable":true,"archived":false,"address":{"company":"Tidewater Supply Co.","address1":"Unit 4, 18 Example Road","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7614,"longitude":151.2675},"rank":100,"bindings":[{"channelId":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","externalId":"store-location-1","externalName":"Warehouse"}],"createdAt":"2026-03-02T09:14:06.000Z","updatedAt":"2026-03-12T07:00:05.000Z"},{"id":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","name":"Shopfront","fulfillable":true,"archived":false,"note":"Counter stock; restocked from Main twice a week.","address":{"company":"Tidewater Supply Co.","address1":"Shop 2, 40 Example Parade","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7633,"longitude":151.2694},"rank":200,"bindings":[],"createdAt":"2026-03-09T02:30:11.000Z","updatedAt":"2026-03-09T02:30:11.000Z"},{"id":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc","name":"Quarantine bay","fulfillable":false,"archived":false,"note":"Returns awaiting inspection. Never sold from.","rank":100,"bindings":[],"createdAt":"2026-10-20T23:05:40.000Z","updatedAt":"2026-10-20T23:05:40.000Z"}],"total":3,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the places this tenant holds stock, oldest first. There is always at least one: a fulfillable location is provisioned when the organization is created, and the last fulfillable one cannot be archived or switched off. `q` is a case-insensitive substring of the name or the note; `archived` and `fulfillable` narrow to one side of each flag, and omitting them means either. Omitting `limit` returns every match in one page — which is what a screen filling a location picker wants, and what this endpoint has always done.\n\nRequires `locations:read`.","x-mcp-tool":{"name":"inventory_list_locations","title":"Inventory: List locations","toolset":"locations","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["locations:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["locations"],"operationId":"locations.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"Open a quarantine bay: stock can be held there but never sold from it.","value":{"id":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc","name":"Quarantine bay","fulfillable":false,"archived":false,"note":"Returns awaiting inspection. Never sold from.","rank":100,"bindings":[],"createdAt":"2026-10-20T23:05:40.000Z","updatedAt":"2026-10-20T23:05:40.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"LocationNameConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationNameConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Open a location. `fulfillable` (default true) is the flag with teeth: stock at a non-fulfillable site can be received, held and transferred, but never reserved, allocated or dispatched to a customer — which is what makes a quarantine bay, a repair bench or a 3PL you have not switched on yet safe to hold stock in. `rank` places it in the order routing walks sites in, lowest first (every site starts at 100, so an unranked tenant routes as it always did). Appends `inventory.location-created`. Idempotent on the name: a second open location with the same name (trimmed, case-insensitive) is refused with 409 `LocationNameConflict`, so a retried open never makes two.\n\nRequires `locations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLocationEncoded"},"example":{"name":"Quarantine bay","fulfillable":false,"note":"Returns awaiting inspection. Never sold from."}}},"required":true},"x-mcp-tool":{"name":"inventory_create_location","title":"Inventory: Create location","toolset":"locations","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}}},"/locations/{locationId}":{"get":{"tags":["locations"],"operationId":"locations.get","parameters":[{"name":"locationId","in":"path","schema":{"$ref":"#/components/schemas/LocId"},"required":true,"example":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"locations.get","value":{"id":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","name":"Main","fulfillable":true,"archived":false,"address":{"company":"Tidewater Supply Co.","address1":"Unit 4, 18 Example Road","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7614,"longitude":151.2675},"rank":100,"bindings":[{"channelId":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","externalId":"store-location-1","externalName":"Warehouse"}],"createdAt":"2026-03-02T09:14:06.000Z","updatedAt":"2026-03-12T07:00:05.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One stock location by its `loc_` id: its name, whether orders may be fulfilled from it, whether it is archived, and its note. Read-only.\n\nRequires `locations:read`.","x-mcp-tool":{"name":"inventory_get_location","title":"Inventory: Get location","toolset":"locations","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["locations:read"],"x-example-source":{"origin":"contract"}},"patch":{"tags":["locations"],"operationId":"locations.update","parameters":[{"name":"locationId","in":"path","schema":{"$ref":"#/components/schemas/LocId"},"required":true,"example":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"Move the shopfront ahead of Main in the routing order.","value":{"id":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","name":"Shopfront","fulfillable":true,"archived":false,"note":"Counter stock; restocked from Main twice a week.","address":{"company":"Tidewater Supply Co.","address1":"Shop 2, 40 Example Parade","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7633,"longitude":151.2694},"rank":50,"bindings":[],"createdAt":"2026-03-09T02:30:11.000Z","updatedAt":"2026-10-22T06:40:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"LastFulfillableLocation | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LastFulfillableLocationEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Rename a location, re-note it, change whether stock there can be sold, or move it in the routing order (`rank`, lowest first). Appends `inventory.location-updated`. 409 `LastFulfillableLocation` if this would leave the tenant with nowhere to ship from. Stock already at the site stays put — making a location non-fulfillable withdraws it from sale rather than moving anything. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `locations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLocationEncoded"},"example":{"rank":50}}},"required":true},"x-mcp-tool":{"name":"inventory_update_location","title":"Inventory: Update location","toolset":"locations","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}}},"/locations/priority":{"put":{"tags":["locations"],"operationId":"locations.prioritise","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"LocationPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationPageEncoded"},"examples":{"contract":{"summary":"Put the shopfront ahead of Main.","value":{"items":[{"id":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","name":"Shopfront","fulfillable":true,"archived":false,"note":"Counter stock; restocked from Main twice a week.","address":{"company":"Tidewater Supply Co.","address1":"Shop 2, 40 Example Parade","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7633,"longitude":151.2694},"rank":10,"bindings":[],"createdAt":"2026-03-09T02:30:11.000Z","updatedAt":"2026-10-29T06:00:00.000Z"},{"id":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","name":"Main","fulfillable":true,"archived":false,"address":{"company":"Tidewater Supply Co.","address1":"Unit 4, 18 Example Road","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7614,"longitude":151.2675},"rank":20,"bindings":[{"channelId":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","externalId":"store-location-1","externalName":"Warehouse"}],"createdAt":"2026-03-02T09:14:06.000Z","updatedAt":"2026-10-29T06:00:00.000Z"},{"id":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc","name":"Quarantine bay","fulfillable":false,"archived":false,"note":"Returns awaiting inspection. Never sold from.","rank":100,"bindings":[],"createdAt":"2026-10-20T23:05:40.000Z","updatedAt":"2026-10-20T23:05:40.000Z"}],"total":3,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set the tenant's site priority — the order routing tries sites in under the `rank` policy, and the tie-break under `nearest` (`docs/order-routing.md`). `locationIds` lists sites highest priority first; each listed site's `rank` becomes its place in the list (10, 20, 30 …), and a site the list leaves out keeps the rank it had. Appends one `inventory.location-updated` (carrying `rank`) per site whose rank moved, in one commit. Idempotent by content: a list that moves no rank appends nothing. 404 `LocationNotFound` for an id the tenant does not have, 409 `LocationArchived` for an archived site. Answers every location in routing order. A catalog's own priority is part of its routing policy (`PUT /workflow`, `routingByCatalog`), not this list.\n\nRequires `locations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLocationPriorityEncoded"},"example":{"locationIds":["loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]}}},"required":true},"x-mcp-withheld":"The admin's drag-to-order list in Settings › Workflow; an agent moves a site in the priority order with inventory_update_location's rank instead.","x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}}},"/locations/{locationId}/archive":{"post":{"tags":["locations"],"operationId":"locations.archive","parameters":[{"name":"locationId","in":"path","schema":{"$ref":"#/components/schemas/LocId"},"required":true,"example":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"locations.archive","value":{"id":"loc_01a15b90-35a0-738e-af06-23ef7db9fddc","name":"Quarantine bay","fulfillable":false,"archived":true,"note":"Returns awaiting inspection. Never sold from.","rank":100,"bindings":[],"createdAt":"2026-10-20T23:05:40.000Z","updatedAt":"2026-10-22T06:45:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"LastFulfillableLocation | LocationNotEmpty | LocationBound | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LastFulfillableLocationEncoded"},{"$ref":"#/components/schemas/LocationNotEmptyEncoded"},{"$ref":"#/components/schemas/LocationBoundEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Close a location to new stock. History is kept and the site stops accepting movements. Appends `inventory.location-archived`. 409 `LocationNotEmpty` if it still holds anything — transfer the stock out first, because archiving it would strand it where nothing can reach it; 409 `LastFulfillableLocation` if it is the only place left to ship from; 409 `LocationBound` while a connected sales channel (a store, a marketplace account) has it as one of its locations — the channel routes orders there. Archiving twice is acknowledged. A retry appends nothing.\n\nRequires `locations:write`.","x-mcp-tool":{"name":"inventory_archive_location","title":"Inventory: Archive location","toolset":"locations","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}}},"/locations/{locationId}/bindings/{channelId}":{"put":{"tags":["locations"],"operationId":"locations.bind","parameters":[{"name":"locationId","in":"path","schema":{"$ref":"#/components/schemas/LocId"},"required":true,"example":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa"},{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"The web store's app pairs its second location with the shopfront.","value":{"id":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","name":"Shopfront","fulfillable":true,"archived":false,"note":"Counter stock; restocked from Main twice a week.","address":{"company":"Tidewater Supply Co.","address1":"Shop 2, 40 Example Parade","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7633,"longitude":151.2694},"rank":200,"bindings":[{"channelId":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","externalId":"store-location-2","externalName":"Shopfront"}],"createdAt":"2026-03-09T02:30:11.000Z","updatedAt":"2026-10-22T06:50:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound | ChannelNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationNotFoundEncoded"},{"$ref":"#/components/schemas/ChannelNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | ChannelNotConnected | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/ChannelNotConnectedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Bind a location to one of a sales channel's locations: `channelId` is the channel (`GET /channels`), `externalId` the channel's own id for its location and `externalName` its name there. A site bound by a connected channel cannot be archived while the binding stands. Called by the app that provides the channel, as it pairs the channel's locations with the tenant's sites. Appends `inventory.location-bound`. 404 `ChannelNotFound`, 409 `ChannelNotConnected` for a disconnected channel, 409 `LocationArchived` for an archived site. Idempotent by content: binding the same channel to the same channel location again is acknowledged and appends nothing; a different one replaces it.\n\nRequires `locations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindLocationEncoded"},"example":{"externalId":"store-location-2","externalName":"Shopfront"}}},"required":true},"x-mcp-withheld":"Called by the app providing a sales channel as it pairs the channel's locations (its location mirror); an agent binds a store location with the channel app's own connection tool instead.","x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["locations"],"operationId":"locations.unbind","parameters":[{"name":"locationId","in":"path","schema":{"$ref":"#/components/schemas/LocId"},"required":true,"example":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"},{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEncoded"},"examples":{"contract":{"summary":"locations.unbind","value":{"id":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","name":"Main","fulfillable":true,"archived":false,"address":{"company":"Tidewater Supply Co.","address1":"Unit 4, 18 Example Road","city":"Brookvale","province":"New South Wales","provinceCode":"NSW","country":"Australia","countryCode":"AU","zip":"2100"},"coordinates":{"latitude":-33.7614,"longitude":151.2675},"rank":100,"bindings":[],"createdAt":"2026-03-02T09:14:06.000Z","updatedAt":"2026-10-22T06:55:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Release a location from one channel's binding — its location was deleted in the channel, or the channel no longer stocks there — so it may be archived again. Appends `inventory.location-unbound`. Idempotent by state: a location that channel does not bind is acknowledged and appends nothing.\n\nRequires `locations:write`.","x-mcp-withheld":"Called by the app providing a sales channel when the channel deletes a location or stops stocking there; an agent disconnects the store or re-reads its locations instead.","x-required-scopes":["locations:write"],"x-example-source":{"origin":"contract"}}},"/products":{"get":{"tags":["products"],"operationId":"products.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false,"example":"widget"},{"name":"status","in":"query","schema":{"type":"string"},"required":false,"example":"active"},{"name":"catalogId","in":"query","schema":{"type":"string"},"required":false},{"name":"holdsSku","in":"query","schema":{"$ref":"#/components/schemas/Sku_1"},"required":false},{"name":"notInCatalogId","in":"query","schema":{"$ref":"#/components/schemas/CatId"},"required":false},{"name":"sort","in":"query","schema":{"$ref":"#/components/schemas/ProductSortKey"},"required":false,"example":"title"},{"name":"order","in":"query","schema":{"$ref":"#/components/schemas/SortOrder"},"required":false,"example":"asc"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"20"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ProductPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPageEncoded"},"examples":{"contract":{"summary":"products.list","value":{"items":[{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e","title":"Widget twin pack","description":"One blue and one red widget in a gift box.","status":"active","handle":"widget-twin-pack","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Gift"],"taxClass":"standard","options":[],"variants":[{"id":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","options":[],"kind":{"_tag":"composite","components":[{"sku":"WIDGET-BLUE","quantity":1},{"sku":"WIDGET-RED","quantity":1}],"barcodes":[{"value":"9300000000033","type":"gtin"}],"hsCodes":[],"weightGrams":500,"packedSize":{"lengthMm":160,"widthMm":120,"heightMm":60}},"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-04-02T05:44:30.000Z"}],"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-04-02T05:44:30.000Z"}],"total":2,"limit":20,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the tenant's products with their variants, newest first. `q` matches title, handle or variant SKU (as `GET /items`), `status` to a comma-separated set of statuses (archived products are listed unless narrowed away), `catalogId` to what one channel catalog lists, `sort`/`order` pick the column and direction (an unknown catalog is a 404; an **archived** one lists nothing — it has been withdrawn, and it resolves empty for every reader). `total` counts every match regardless of the page; `limit` is 1-200 and omitting it returns every match; page with `offset`.\n\nRequires `products:read` or `orders:read` or `catalogs:read`.","x-mcp-tool":{"name":"catalog_list_products","title":"Catalog: List products","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","orders:read","catalogs:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["products"],"operationId":"products.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"A product with two colours, each variant an existing stocked SKU.","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"VariantSkuConflict | SkuNotStocked | CompositeSkuIsStocked | SkuNotAllowed | VariantOptionsInvalid | BarcodeConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/VariantSkuConflictEncoded"},{"$ref":"#/components/schemas/SkuNotStockedEncoded"},{"$ref":"#/components/schemas/CompositeSkuIsStockedEncoded"},{"$ref":"#/components/schemas/SkuNotAllowedEncoded"},{"$ref":"#/components/schemas/VariantOptionsInvalidEncoded"},{"$ref":"#/components/schemas/BarcodeConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Open a product with at least one variant, each with its own tenant-unique SKU and a `kind`: `stocked` (the SKU is an inventory item, else 409 `SkuNotStocked`) or `composite` (a kit of `components`, stocked SKUs in fixed quantities; its own SKU must not be an inventory item (409 `CompositeSkuIsStocked`) and fits the tenant's `skuAlphabet` (409 `SkuNotAllowed`); a kit carries its own trade codes, measurements and order rules on `kind` (409 `BarcodeConflict` for another SKU's barcode). `options` declares up to 3 axes; each variant selects one value per axis and no two share a selection (409 `VariantOptionsInvalid`). The storefront metadata is what a storefront channel carries: `handle` (minted from the title when omitted, made unique with `-2`, `-3` …), `vendor`, `productType`, `category`, `tags`, `seo`. Appends `inventory.product-created`. Idempotent on its variants' SKUs: a retried create meets 409 `VariantSkuConflict`, never a second product.\n\nRequires `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductEncoded"},"example":{"title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"}},{"sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"}}]}}},"required":true},"x-mcp-tool":{"name":"catalog_create_product","title":"Catalog: Create product","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}":{"get":{"tags":["products"],"operationId":"products.get","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"products.get","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One product by its `prd_` id, with all of its variants (each variant's SKU, option values and list price) and its options. 404 `ProductNotFound` when it does not exist. Read-only.\n\nRequires `products:read` or `orders:read` or `catalogs:read`.","x-mcp-tool":{"name":"catalog_get_product","title":"Catalog: Get product","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","orders:read","catalogs:read"],"x-example-source":{"origin":"contract"}},"patch":{"tags":["products"],"operationId":"products.update","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"Retag the product and give it a search description.","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller","Kitchen"],"seo":{"title":"Widget — moulded, dishwasher safe","description":"A moulded widget for everyday fixing jobs, in blue or red."},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-10-22T07:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"ProductArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Retitle or re-describe a product, move it between `active` and `draft`, or set its metadata — `handle`, `vendor`, `productType`, `category`, `tags`, `seo`, the fields a storefront's product carries. Metadata is a patch: an absent field is left alone, `null` clears it, a value replaces it, and `tags` is replaced whole. A `handle` cannot be cleared, and one another product holds is suffixed (`-2`, `-3`, …) rather than refused — read it back. Appends `inventory.product-updated`. 409 `ProductArchived` once archived. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductEncoded"},"example":{"tags":["Hardware","Bestseller","Kitchen"],"seo":{"title":"Widget — moulded, dishwasher safe","description":"A moulded widget for everyday fixing jobs, in blue or red."}}}},"required":true},"x-mcp-tool":{"name":"catalog_update_product","title":"Catalog: Update product","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/options":{"put":{"tags":["products"],"operationId":"products.setOptions","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"Add a third colour to the axis before its variant is added.","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red","Green"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-10-21T03:11:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound | VariantNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductNotFoundEncoded"},{"$ref":"#/components/schemas/VariantNotFoundEncoded"}]}}}},"409":{"description":"ProductArchived | VariantOptionsInvalid | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductArchivedEncoded"},{"$ref":"#/components/schemas/VariantOptionsInvalidEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Re-declare the axes a product varies on (max 3) and, in the same command, where each variant sits in the new option space. `variants` keys selections by SKU; a variant left out keeps its current selection. Every variant must end with one value per declared axis, drawn from that axis's values, and no two variants may share a selection — 409 `VariantOptionsInvalid` refuses the whole command otherwise, and a SKU the product does not carry is 404 `VariantNotFound`. Appends `inventory.product-options-set` carrying every variant's final selection. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProductOptionsEncoded"},"example":{"options":[{"name":"Colour","values":["Blue","Red","Green"]}]}}},"required":true},"x-mcp-tool":{"name":"catalog_set_product_options","title":"Catalog: Set product options","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/archive":{"post":{"tags":["products"],"operationId":"products.archive","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"products.archive","value":{"id":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e","title":"Widget twin pack","description":"One blue and one red widget in a gift box.","status":"archived","handle":"widget-twin-pack","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Gift"],"taxClass":"standard","options":[],"variants":[{"id":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","options":[],"kind":{"_tag":"composite","components":[{"sku":"WIDGET-BLUE","quantity":1},{"sku":"WIDGET-RED","quantity":1}],"barcodes":[{"value":"9300000000033","type":"gtin"}],"hsCodes":[],"weightGrams":500,"packedSize":{"lengthMm":160,"widthMm":120,"heightMm":60}},"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-04-02T05:44:30.000Z"}],"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-10-22T07:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Withdraw a product from sale for good. Its variants and their SKUs stay readable and keep answering availability; nothing about the product can change afterwards. Appends `inventory.product-archived`. Archiving twice is acknowledged. A retry appends nothing.\n\nRequires `products:write`.","x-mcp-tool":{"name":"catalog_archive_product","title":"Catalog: Archive product","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/variants":{"post":{"tags":["products"],"operationId":"products.addVariant","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"201":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"Add the green widget; WIDGET-GREEN is already a stocked item.","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red","Green"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_01a15c72-67e0-79db-818b-f233786beac6","sku":"WIDGET-GREEN","options":[{"name":"Colour","value":"Green"}],"kind":{"_tag":"stocked"},"createdAt":"2026-10-21T03:12:44.000Z","updatedAt":"2026-10-21T03:12:44.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-10-21T03:12:44.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"ProductArchived | VariantSkuConflict | SkuNotStocked | CompositeSkuIsStocked | SkuNotAllowed | VariantOptionsInvalid | BarcodeConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductArchivedEncoded"},{"$ref":"#/components/schemas/VariantSkuConflictEncoded"},{"$ref":"#/components/schemas/SkuNotStockedEncoded"},{"$ref":"#/components/schemas/CompositeSkuIsStockedEncoded"},{"$ref":"#/components/schemas/SkuNotAllowedEncoded"},{"$ref":"#/components/schemas/VariantOptionsInvalidEncoded"},{"$ref":"#/components/schemas/BarcodeConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Add a variant to a product, under the same rules as creation. Appends `inventory.variant-added`. Idempotent on the SKU: a retried add meets 409 `VariantSkuConflict`, never a second variant.\n\nRequires `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariantEncoded"},"example":{"sku":"WIDGET-GREEN","options":[{"name":"Colour","value":"Green"}],"kind":{"_tag":"stocked"}}}},"required":true},"x-mcp-tool":{"name":"catalog_add_variant","title":"Catalog: Add variant","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/variants/{variantId}":{"patch":{"tags":["products"],"operationId":"products.updateVariant","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e"},{"name":"variantId","in":"path","schema":{"$ref":"#/components/schemas/VarId"},"required":true,"example":"var_019d4cb8-c618-7383-84f4-8228073621c6"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"Name the kit's variant and correct its packed weight.","value":{"id":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e","title":"Widget twin pack","description":"One blue and one red widget in a gift box.","status":"active","handle":"widget-twin-pack","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Gift"],"taxClass":"standard","options":[],"variants":[{"id":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","title":"Twin pack","options":[],"kind":{"_tag":"composite","components":[{"sku":"WIDGET-BLUE","quantity":1},{"sku":"WIDGET-RED","quantity":1}],"barcodes":[{"value":"9300000000033","type":"gtin"}],"hsCodes":[],"weightGrams":520,"packedSize":{"lengthMm":160,"widthMm":120,"heightMm":60}},"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-10-22T07:20:00.000Z"}],"createdAt":"2026-04-02T05:44:30.000Z","updatedAt":"2026-10-22T07:20:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound | VariantNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductNotFoundEncoded"},{"$ref":"#/components/schemas/VariantNotFoundEncoded"}]}}}},"409":{"description":"ProductArchived | VariantOptionsInvalid | VariantNotComposite | SkuNotStocked | BarcodeConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductArchivedEncoded"},{"$ref":"#/components/schemas/VariantOptionsInvalidEncoded"},{"$ref":"#/components/schemas/VariantNotCompositeEncoded"},{"$ref":"#/components/schemas/SkuNotStockedEncoded"},{"$ref":"#/components/schemas/BarcodeConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Change a variant's title, its option selection, or — for a kit (composite) — its recipe (`components`), trade codes (409 `BarcodeConflict`), measurements and order rules (`null` clears); those on a stocked variant are 409 `VariantNotComposite`, being its item's. The SKU is not editable: a new SKU is a new variant. Appends `inventory.variant-updated`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `products:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVariantEncoded"},"example":{"title":"Twin pack","weightGrams":520}}},"required":true},"x-mcp-tool":{"name":"catalog_update_variant","title":"Catalog: Update variant","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["products"],"operationId":"products.removeVariant","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"},{"name":"variantId","in":"path","schema":{"$ref":"#/components/schemas/VarId"},"required":true,"example":"var_01a15c72-67e0-79db-818b-f233786beac6"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"products.removeVariant","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red","Green"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-10-22T07:30:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound | VariantNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductNotFoundEncoded"},{"$ref":"#/components/schemas/VariantNotFoundEncoded"}]}}}},"409":{"description":"ProductArchived | LastVariant | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductArchivedEncoded"},{"$ref":"#/components/schemas/LastVariantEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Remove a variant from its product. The SKU becomes free for another variant; inventory's item (if any) is untouched. 409 `LastVariant` on the only variant — archive the product instead. Appends `inventory.variant-removed`. Idempotent: a retry finds no variant to remove (404) and appends nothing.\n\nRequires `products:write`.","x-mcp-tool":{"name":"catalog_remove_variant","title":"Catalog: Remove variant","toolset":"catalog","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/availability":{"get":{"tags":["products"],"operationId":"products.availability","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ProductAvailability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductAvailabilityEncoded"},"examples":{"contract":{"summary":"products.availability","value":{"productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","variants":[{"variantId":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","kind":"stocked","onHand":158,"available":148,"projected":178},{"variantId":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","kind":"stocked","onHand":0,"available":0,"projected":-4}],"asOf":"2026-10-22T05:30:01.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"What can be promised of each variant right now, derived from the stock projection at query time — never stored. A stocked variant reports its SKU's `available` (fulfillable sites only), `onHand` and `projected`. A composite reports the **divisible sum** of its parts: each figure is the minimum over components of `floor(part / quantity)`, with the per-component breakdown and `limitedBy` naming the binding SKUs.\n\nRequires `products:read` or `orders:read` or `catalogs:read`.","x-mcp-tool":{"name":"catalog_product_availability","title":"Catalog: Product availability","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","orders:read","catalogs:read"],"x-example-source":{"origin":"contract"}}},"/variants/{sku}":{"get":{"tags":["products"],"operationId":"products.variant","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEncoded"},"examples":{"contract":{"summary":"products.variant","value":{"id":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"id":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"},{"id":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":{"_tag":"stocked"},"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}],"createdAt":"2026-03-10T01:10:00.000Z","updatedAt":"2026-03-10T01:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"VariantNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The product a SKU belongs to, by the SKU of one of its variants. SKUs are unique across the catalog, so this is a single answer.\n\nRequires `products:read` or `orders:read` or `catalogs:read`.","x-mcp-tool":{"name":"catalog_get_variant","title":"Catalog: Get variant","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","orders:read","catalogs:read"],"x-example-source":{"origin":"contract"}}},"/variants/{sku}/availability":{"get":{"tags":["products"],"operationId":"products.variantAvailability","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-PAIR"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"VariantAvailability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantAvailabilityEncoded"},"examples":{"contract":{"summary":"A kit's availability: the fewest whole kits its parts make, red being the part that runs out.","value":{"variantId":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","kind":"composite","onHand":0,"available":0,"projected":-4,"components":[{"sku":"WIDGET-BLUE","quantity":1,"available":148,"kits":148},{"sku":"WIDGET-RED","quantity":1,"available":0,"kits":0}],"limitedBy":["WIDGET-RED"]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"VariantNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One variant's availability by SKU — the storefront's question. Same derivation as the product-level view.\n\nRequires `products:read` or `orders:read` or `catalogs:read`.","x-mcp-tool":{"name":"catalog_variant_availability","title":"Catalog: Variant availability","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","orders:read","catalogs:read"],"x-example-source":{"origin":"contract"}}},"/items/{sku}/assets":{"get":{"tags":["assets"],"operationId":"assets.listForItem","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetViewEncoded"}},"examples":{"contract":{"summary":"assets.listForItem","value":[{"id":"ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149","owner":{"_tag":"sku","sku":"WIDGET-BLUE"},"filename":"widget-blue.jpg","contentType":"image/jpeg","size":348112,"uploadedAt":"2026-04-11T08:22:10.000Z","url":"https://files.example.com/org_019cadd3-7f48-7813-b601-1d0e5ec31353/ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=5f0c2b9e7d4a1f3c8e6b0a9d2c4f7e1b3a5d8c0f2e4b6a9c1d3f5e7a9b0c2d4e","urlExpiresAt":"2026-10-22T05:45:01.000Z"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"The files attached to a SKU, newest first, each with a signed URL valid for fifteen minutes (`urlExpiresAt`). Ask again for a fresh one.\n\nRequires `products:read` or `stock:read`.","x-mcp-tool":{"name":"catalog_list_item_assets","title":"Catalog: List item assets","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","stock:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["assets"],"operationId":"assets.uploadForItem","parameters":[{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-PHOTO"},{"name":"filename","in":"query","schema":{"$ref":"#/components/schemas/AssetFilename"},"required":true,"example":"front.png"},{"name":"reference","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"example":"upload:WIDGET-PHOTO:front"}],"security":[{"bearer":[]}],"responses":{"201":{"description":"AssetView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetViewEncoded"},"examples":{"attach-files":{"summary":"Attach a photo to a SKU","value":{"id":"ast_01a15861-f150-7e8f-9a0b-1c2d3e4f5a6b","owner":{"_tag":"sku","sku":"WIDGET-PHOTO"},"filename":"front.png","contentType":"image/png","size":27,"uploadedAt":"2026-08-17T09:00:00.000Z","url":"https://files.example/org_…/ast_3c1f9a2e-…?X-Amz-Expires=900&X-Amz-Signature=…","urlExpiresAt":"2026-08-17T09:00:00.000Z"}}}}}},"400":{"description":"AssetUnreadable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetUnreadableEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ItemNotFound | AssetNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/AssetNotFoundEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"413":{"description":"AssetTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetTooLargeEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"Attach a file to a SKU. The body is the raw file — not multipart, not JSON — streamed into the private bucket, with `filename` and the upload's `reference` in the query string and the media type in `Content-Type`. At most 100 MiB: a larger `Content-Length` is refused before a byte is read, and a body that grows past the cap is cut off with 413 `AssetTooLarge` and nothing stored. Appends `inventory.asset-uploaded` and answers the asset with a signed URL (201). Idempotent on `reference`: the asset id is derived from it, so a retry re-mints the same `ast_` id, is acknowledged from the journal and appends nothing. 404 `ItemNotFound` if the owner does not exist; 404 `AssetNotFound` if the retried upload's asset has since been removed.\n\nRequires `products:write` or `stock:write`.","x-mcp-withheld":"The file's raw bytes are the request body, which a JSON tool call cannot carry; photos and spec sheets are uploaded in the admin.","x-required-scopes":["products:write","stock:write"],"x-example-source":{"origin":"workflow","workflow":"attach-files","step":2},"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"},"example":"‰PNG\r\n\u001a\n(not really a png)"}}}}},"/products/{productId}/assets":{"get":{"tags":["assets"],"operationId":"assets.listForProduct","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetViewEncoded"}},"examples":{"contract":{"summary":"assets.listForProduct","value":[{"id":"ast_16b10778-34b4-8922-a950-e6b57cc5017c","owner":{"_tag":"product","productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"},"filename":"widget-spec-sheet.pdf","contentType":"application/pdf","size":182406,"uploadedAt":"2026-10-22T04:40:00.000Z","url":"https://files.example.com/org_019cadd3-7f48-7813-b601-1d0e5ec31353/ast_16b10778-34b4-8922-a950-e6b57cc5017c?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=5f0c2b9e7d4a1f3c8e6b0a9d2c4f7e1b3a5d8c0f2e4b6a9c1d3f5e7a9b0c2d4e","urlExpiresAt":"2026-10-22T05:45:01.000Z"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"The files attached to a product, newest first, each with a signed URL valid for fifteen minutes (`urlExpiresAt`).\n\nRequires `products:read` or `stock:read`.","x-mcp-tool":{"name":"catalog_list_product_assets","title":"Catalog: List product assets","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","stock:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["assets"],"operationId":"assets.uploadForProduct","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"},{"name":"filename","in":"query","schema":{"$ref":"#/components/schemas/AssetFilename"},"required":true,"example":"widget-spec-sheet.pdf"},{"name":"reference","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"example":"widget-spec-sheet-v2"}],"security":[{"bearer":[]}],"responses":{"201":{"description":"AssetView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetViewEncoded"},"examples":{"contract":{"summary":"Send the PDF as the raw request body, with `Content-Type: application/pdf`.","value":{"id":"ast_16b10778-34b4-8922-a950-e6b57cc5017c","owner":{"_tag":"product","productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"},"filename":"widget-spec-sheet.pdf","contentType":"application/pdf","size":182406,"uploadedAt":"2026-10-22T04:40:00.000Z","url":"https://files.example.com/org_019cadd3-7f48-7813-b601-1d0e5ec31353/ast_16b10778-34b4-8922-a950-e6b57cc5017c?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=5f0c2b9e7d4a1f3c8e6b0a9d2c4f7e1b3a5d8c0f2e4b6a9c1d3f5e7a9b0c2d4e","urlExpiresAt":"2026-10-22T04:55:00.000Z"}}}}}},"400":{"description":"AssetUnreadable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetUnreadableEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound | AssetNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ProductNotFoundEncoded"},{"$ref":"#/components/schemas/AssetNotFoundEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"413":{"description":"AssetTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetTooLargeEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"Attach a file to a product. The body is the raw file — not multipart, not JSON — streamed into the private bucket, with `filename` and the upload's `reference` in the query string and the media type in `Content-Type`. At most 100 MiB: a larger `Content-Length` is refused before a byte is read, and a body that grows past the cap is cut off with 413 `AssetTooLarge` and nothing stored. Appends `inventory.asset-uploaded` and answers the asset with a signed URL (201). Idempotent on `reference`: the asset id is derived from it, so a retry re-mints the same `ast_` id, is acknowledged from the journal and appends nothing. 404 `ProductNotFound` if the owner does not exist; 404 `AssetNotFound` if the retried upload's asset has since been removed.\n\nRequires `products:write`.","x-mcp-withheld":"The file's raw bytes are the request body, which a JSON tool call cannot carry; photos and spec sheets are uploaded in the admin.","x-required-scopes":["products:write"],"x-example-source":{"origin":"contract"},"requestBody":{"required":true,"content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"example":"%PDF-1.7 … (the spec sheet's bytes)"}}}}},"/assets/{assetId}":{"get":{"tags":["assets"],"operationId":"assets.get","parameters":[{"name":"assetId","in":"path","schema":{"$ref":"#/components/schemas/AstId"},"required":true,"example":"ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"AssetView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetViewEncoded"},"examples":{"contract":{"summary":"assets.get","value":{"id":"ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149","owner":{"_tag":"sku","sku":"WIDGET-BLUE"},"filename":"widget-blue.jpg","contentType":"image/jpeg","size":348112,"uploadedAt":"2026-04-11T08:22:10.000Z","url":"https://files.example.com/org_019cadd3-7f48-7813-b601-1d0e5ec31353/ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=5f0c2b9e7d4a1f3c8e6b0a9d2c4f7e1b3a5d8c0f2e4b6a9c1d3f5e7a9b0c2d4e","urlExpiresAt":"2026-10-22T05:45:01.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"AssetNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"One stored file (a SKU's or product's photo or spec sheet) by its `ast_` id: filename, content type, size, and a fresh short-lived signed `url` to fetch the bytes from, valid until `urlExpiresAt`. Read-only.\n\nRequires `products:read` or `stock:read`.","x-mcp-tool":{"name":"catalog_get_asset","title":"Catalog: Get asset","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:read","stock:read"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["assets"],"operationId":"assets.remove","parameters":[{"name":"assetId","in":"path","schema":{"$ref":"#/components/schemas/AstId"},"required":true,"example":"ast_01a15861-f150-7e8f-9a0b-1c2d3e4f5a6b"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetEncoded"},"examples":{"attach-files":{"summary":"Attach a photo to a SKU","value":{"id":"ast_01a15861-f150-7e8f-9a0b-1c2d3e4f5a6b","owner":{"_tag":"sku","sku":"WIDGET-PHOTO"},"filename":"front.png","contentType":"image/png","size":27,"uploadedAt":"2026-08-17T09:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"AssetOwnerScopeRequired | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetOwnerScopeRequiredEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"AssetNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Detach and delete a file, answering with the asset as it was. A product's file takes `products:write` (403 `AssetOwnerScopeRequired`). Appends `inventory.asset-removed`; the object is deleted from the bucket after the fact commits. Idempotent: a retry meets 404 and appends nothing.\n\nRequires `products:write` or `stock:write`.","x-mcp-tool":{"name":"catalog_remove_asset","title":"Catalog: Remove asset","toolset":"catalog","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["products:write","stock:write"],"x-example-source":{"origin":"workflow","workflow":"attach-files","step":5}}},"/assets/{assetId}/content":{"get":{"tags":["assets"],"operationId":"assets.content","parameters":[{"name":"assetId","in":"path","schema":{"$ref":"#/components/schemas/AstId"},"required":true,"example":"ast_0097228e-4607-6b0a-ce7b-1fb43ebf3149"}],"security":[{"bearer":[]}],"responses":{"302":{"description":"<No Content>"},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"AssetNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"AssetStoreUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetStoreUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"The bytes, for a caller holding a session rather than a signed URL: answers 302 to a signed URL for the object. The bucket is private, so this and the signed URLs the reads carry are the only ways at a file.\n\nRequires `products:read` or `stock:read`.","x-mcp-withheld":"Answers a redirect to the object's bytes; `catalog_get_asset` returns the short-lived signed URL an agent can hand on instead.","x-required-scopes":["products:read","stock:read"],"x-example-source":{"origin":"contract"}}},"/catalogs":{"get":{"tags":["catalogs"],"operationId":"catalogs.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false},{"name":"status","in":"query","schema":{"type":"string"},"required":false,"example":"active"},{"name":"sort","in":"query","schema":{"$ref":"#/components/schemas/CatalogSortKey"},"required":false,"example":"name"},{"name":"order","in":"query","schema":{"$ref":"#/components/schemas/SortOrder"},"required":false,"example":"asc"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPageEncoded"},"examples":{"contract":{"summary":"catalogs.list","value":{"items":[{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":2,"priceCount":3,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-04-02T05:50:12.000Z"},{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"active","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-05-18T04:31:45.000Z"}],"total":2,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of this tenant's channel catalogs, newest first — the named sets of products, per-SKU prices and locations a selling view (an online store, a POS register, a B2B company) is allowed to see. Never empty: every tenant is provisioned with a `Default` catalog (in the home currency) the moment its organization exists, beside its `Main` location. `q` narrows by name or currency (case-insensitive substring), `status` to a comma-separated set of statuses (archived catalogs are listed, marked by `status`, unless narrowed away), `sort`/`order` pick the column and direction. `total` counts every match regardless of the page; `limit` is 1-200 and omitting it returns every match; page with `offset`.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_list_catalogs","title":"Catalog: List catalogs","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["catalogs"],"operationId":"catalogs.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"catalogs.create","value":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"active","productCount":0,"priceCount":0,"pricing":{"_tag":"manual"},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-05-18T04:20:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"CatalogNameConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogNameConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Open a catalog: a name (unique among the tenant's active catalogs, because names are how views are assigned) and its one ISO 4217 currency. It starts empty — products opt in, nothing leaks in. `taxInclusive` says whether its prices include tax — `inclusive`, `exclusive`, or `tenant-default` (the default: the tax settings' `defaultConvention`). Appends `inventory.catalog-created`. Idempotent on the name: a retried open meets 409 `CatalogNameConflict`, never a second catalog.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCatalogEncoded"},"example":{"name":"Wholesale","currency":"AUD","taxInclusive":"exclusive"}}},"required":true},"x-mcp-tool":{"name":"catalog_create_catalog","title":"Catalog: Create catalog","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}":{"get":{"tags":["catalogs"],"operationId":"catalogs.get","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"catalogs.get","value":{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":2,"priceCount":3,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-04-02T05:50:12.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One catalog: its name, currency, pricing, location scope and how many products it lists (`productCount`) and SKUs it stores a price for (`priceCount`). The products and prices themselves are `GET /catalogs/:catalogId/products` and `/prices`, a page at a time.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_get_catalog","title":"Catalog: Get catalog","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}},"patch":{"tags":["catalogs"],"operationId":"catalogs.update","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"Rename the wholesale catalog and hold its lines to a 25 % margin.","value":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Trade","currency":"AUD","status":"active","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-10-22T08:00:00.000Z","minimumMarginBps":2500}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | CatalogNameConflict | CompareAtCatalogInvalid | CatalogCurrencyFixed | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/CatalogNameConflictEncoded"},{"$ref":"#/components/schemas/CompareAtCatalogInvalidEncoded"},{"$ref":"#/components/schemas/CatalogCurrencyFixedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Rename a catalog, change its currency, or name its compare-at catalog (`compareAtCatalogId`, `null` clears): the catalog whose price, when higher, every read serves beside this one's as `compareAtCents`, struck through. It must be another active catalog in the same currency (409 `CompareAtCatalogInvalid`). The currency is fixed once it holds prices or another catalog derives from or compares against it (409 `CatalogCurrencyFixed`). `taxInclusive` changes whether its prices include tax, without restating them. Appends `inventory.catalog-updated`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogEncoded"},"example":{"name":"Trade","minimumMarginBps":2500}}},"required":true},"x-mcp-tool":{"name":"catalog_update_catalog","title":"Catalog: Update catalog","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/products":{"get":{"tags":["catalogs"],"operationId":"catalogs.products","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"productId","in":"query","schema":{"type":"string"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"100"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogListingPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogListingPageEncoded"},"examples":{"contract":{"summary":"catalogs.products","value":{"items":[{"productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"},{"productId":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e"}],"total":2,"limit":100,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the products this catalog lists, product-id ascending — every listing, archived products included (the view is what hides those). `productId` asks about named products instead: the ones listed come back, so a screen showing a page of products learns which are in the catalog in one read. `limit` is 1–500, 100 when omitted.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_list_catalog_products","title":"Catalog: List catalog products","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/prices":{"get":{"tags":["catalogs"],"operationId":"catalogs.prices","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"sku","in":"query","schema":{"type":"string"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"100"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogPricePage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPricePageEncoded"},"examples":{"contract":{"summary":"catalogs.prices","value":{"items":[{"sku":"WIDGET-BLUE","priceCents":2495,"breaks":[{"minQuantity":10,"priceCents":2195}]},{"sku":"WIDGET-PAIR","priceCents":4495},{"sku":"WIDGET-RED","priceCents":2495}],"total":3,"limit":100,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of this catalog's prices as it answers them, SKU ascending: its stored rows, and in an `auto` catalog a derived row (marked `auto`) for every SKU its base prices that it does not override. `sku` asks about named SKUs instead: the priced ones come back. `limit` is 1–500, 100 when omitted.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_list_catalog_prices","title":"Catalog: List catalog prices","toolset":"pricing","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}}},"/products/{productId}/catalogs":{"get":{"tags":["catalogs"],"operationId":"catalogs.productCatalogs","parameters":[{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ProductCatalogs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCatalogsEncoded"},"examples":{"contract":{"summary":"Retail stores its prices, GST included; wholesale takes the GST out, then 30 % off, rounded up to 95 cents.","value":{"productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","catalogs":[{"catalog":{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":2,"priceCount":3,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-04-02T05:50:12.000Z"},"listed":true,"prices":[{"sku":"WIDGET-BLUE","priceCents":2495,"breaks":[{"minQuantity":10,"priceCents":2195}]},{"sku":"WIDGET-RED","priceCents":2495}]},{"catalog":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"active","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-05-18T04:31:45.000Z"},"listed":true,"prices":[{"sku":"WIDGET-BLUE","priceCents":1595,"breaks":[{"minQuantity":10,"priceCents":1495}],"auto":true},{"sku":"WIDGET-RED","priceCents":1595,"auto":true}]}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ProductNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Every catalog of the tenant against one product: whether it lists the product, and the product's SKUs priced there as the catalog answers them. Bounded by the tenant's catalogs and the product's variants, never by what the catalogs list.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_product_catalogs","title":"Catalog: Product catalogs","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/archive":{"post":{"tags":["catalogs"],"operationId":"catalogs.archive","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"catalogs.archive","value":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"archived","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-10-22T08:05:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Withdraw a catalog for good. History stays readable; every view still assigned to it sees an empty catalog. Idempotent. Appends `inventory.catalog-archived`; a retry appends nothing.\n\nRequires `catalogs:write`.","x-mcp-tool":{"name":"catalog_archive_catalog","title":"Catalog: Archive catalog","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/pricing":{"put":{"tags":["catalogs"],"operationId":"catalogs.configurePricing","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"Price wholesale at 30 % off retail before GST, rounded up to the next 95 cents.","value":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"active","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-05-18T04:31:45.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | CatalogPricingInvalid | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/CatalogPricingInvalidEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Choose how this catalog is priced. `manual` (the default): every price is a fact a person set. `auto`: derive a price for every SKU its `base` prices — `{ _tag: catalog, catalogId }`, another catalog's stored rows (every SKU that catalog prices), or `{ _tag: cost }`, the SKU's cost basis in the home currency (`GET /items/:sku/cost`; every SKU this catalog lists that has one) — converted at the recorded forex rate for the current hour when the currencies differ (`PUT /fx/rates`), stepped by the optional `adjustment` (`markup`, `margin` or `discount`, in basis points: cost + 40 % is markup 4000, a 40 % margin is margin 4000, less 10 % is discount 1000) and rounded **up** by the optional `rounding` table (bands by `fromCents`, each to the next figure ending in `endingCents` modulo `stepCents`). A base row's quantity breaks are derived the same way. Derived prices are served marked `auto` on every read and never stored; a price set by hand stands as an override until removed; with no rate for the pair only the manual rows are served. `channel`: the channel publishing this catalog prices it itself — manifold derives nothing, and hand-set rows are the fixed-price overrides a sync lays over its prices. 409 `CatalogPricingInvalid` for a base that is this catalog, missing, archived, or itself `auto` (derivation is one hop). Appends `inventory.catalog-pricing-configured`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPricing"},"example":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]}}},"required":true},"x-mcp-tool":{"name":"catalog_configure_pricing","title":"Catalog: Configure pricing","toolset":"pricing","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/fx/rates":{"get":{"tags":["catalogs"],"operationId":"catalogs.fxRates","parameters":[{"name":"base","in":"query","schema":{"type":"string"},"required":false,"example":"AUD"},{"name":"quote","in":"query","schema":{"type":"string"},"required":false,"example":"NZD"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FxRate"}},"examples":{"contract":{"summary":"catalogs.fxRates","value":[{"base":"AUD","quote":"NZD","rateMicros":1092500,"windowStart":"2026-10-22T01:00:00.000Z"},{"base":"AUD","quote":"NZD","rateMicros":1091800,"windowStart":"2026-10-22T00:00:00.000Z"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The recorded forex windows, newest first — optionally narrowed to a `base`/`quote` pair. Each row is the rate in force for the hour beginning at its `windowStart`; an hour with no recording falls back to the newest window before it.\n\nRequires `catalogs:read`.","x-mcp-tool":{"name":"catalog_list_fx_rates","title":"Catalog: List FX rates","toolset":"pricing","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["catalogs"],"operationId":"catalogs.recordFxRate","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"FxRate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FxRate"},"examples":{"contract":{"summary":"One Australian dollar buys 1.0925 New Zealand dollars from 01:00 UTC.","value":{"base":"AUD","quote":"NZD","rateMicros":1092500,"windowStart":"2026-10-22T01:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Record the forex rate for one hour-long window: `rateMicros` millionths of a `quote` unit per `base` unit, in force from the hour-aligned `windowStart`. Auto-priced catalogs read the newest window at or before the current hour; re-recording a window replaces its figure (a correction, journalled like the first). Appends `inventory.fx-rate-recorded`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordFxRateEncoded"},"example":{"base":"AUD","quote":"NZD","rateMicros":1092500,"windowStart":"2026-10-22T01:00:00.000Z"}}},"required":true},"x-mcp-tool":{"name":"catalog_record_fx_rate","title":"Catalog: Record FX rate","toolset":"pricing","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/products/{productId}":{"put":{"tags":["catalogs"],"operationId":"catalogs.includeProduct","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"},{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"catalogs.includeProduct","value":{"id":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","name":"Wholesale","currency":"AUD","status":"active","productCount":2,"priceCount":0,"pricing":{"_tag":"auto","base":{"_tag":"catalog","catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},"adjustment":{"_tag":"discount","basisPoints":3000},"rounding":[{"fromCents":0,"stepCents":100,"endingCents":95}]},"taxInclusive":"exclusive","createdAt":"2026-05-18T04:20:00.000Z","updatedAt":"2026-10-22T08:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound | ProductNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogNotFoundEncoded"},{"$ref":"#/components/schemas/ProductNotFoundEncoded"}]}}}},"409":{"description":"CatalogArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Expose a product (all its variants) to this catalog's views. Including an already-included product acknowledges idempotently. Appends `inventory.catalog-product-included`; a retry appends nothing.\n\nRequires `catalogs:write`.","x-mcp-tool":{"name":"catalog_include_product","title":"Catalog: Include product","toolset":"catalog","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["catalogs"],"operationId":"catalogs.excludeProduct","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"productId","in":"path","schema":{"$ref":"#/components/schemas/PrdId"},"required":true,"example":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"Withdraw the twin pack from retail; its price goes with it.","value":{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":1,"priceCount":2,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-10-22T08:15:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Withdraw a product from this catalog's views. The prices of the SKUs it brought go with it — a price without its product is inert. Appends `inventory.catalog-product-excluded`. Idempotent: a retry is acknowledged and appends nothing.\n\nRequires `catalogs:write`.","x-mcp-tool":{"name":"catalog_exclude_product","title":"Catalog: Exclude product","toolset":"catalog","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/prices/{sku}":{"put":{"tags":["catalogs"],"operationId":"catalogs.setPrice","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-RED"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"Price the red widget at $24.95.","value":{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":2,"priceCount":3,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-10-22T08:20:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | PriceForUnlistedSku | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/PriceForUnlistedSkuEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Price one SKU in this catalog's currency — composite (kit) SKUs price exactly like stocked ones. The SKU's product must already be included; setting a price twice replaces it. Appends `inventory.catalog-price-set`. Idempotent by content: a retry setting the same price appends nothing.\n\nRequires `catalogs:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetCatalogPriceEncoded"},"example":{"priceCents":2495}}},"required":true},"x-mcp-tool":{"name":"catalog_set_price","title":"Catalog: Set price","toolset":"pricing","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["catalogs"],"operationId":"catalogs.removePrice","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"},{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-PAIR"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEncoded"},"examples":{"contract":{"summary":"catalogs.removePrice","value":{"id":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","status":"active","productCount":2,"priceCount":2,"pricing":{"_tag":"manual"},"taxInclusive":"tenant-default","createdAt":"2026-03-02T09:14:06.500Z","updatedAt":"2026-10-22T08:25:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Forget one SKU's price; the SKU stays listed, unpriced. Appends `inventory.catalog-price-removed`. Idempotent: a retry is acknowledged and appends nothing.\n\nRequires `catalogs:write`.","x-mcp-tool":{"name":"catalog_remove_price","title":"Catalog: Remove price","toolset":"pricing","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["catalogs:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/view":{"get":{"tags":["catalogs"],"operationId":"catalogs.view","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogViewEncoded"},"examples":{"contract":{"summary":"catalogs.view","value":{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","name":"Default","currency":"AUD","products":[{"productId":"prd_019cd54b-2e40-7921-ac50-698c7db3cbeb","title":"Widget","description":"A moulded widget for everyday fixing jobs. Dishwasher safe.","status":"active","handle":"widget","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Bestseller"],"seo":{"title":"Widget — moulded, dishwasher safe"},"taxClass":"standard","options":[{"name":"Colour","values":["Blue","Red"]}],"variants":[{"variantId":"var_019cd54b-2e4a-7ee1-b04a-3bb14b60736f","sku":"WIDGET-BLUE","options":[{"name":"Colour","value":"Blue"}],"kind":"stocked","priceCents":2495},{"variantId":"var_019cd54b-2e54-72b7-ae20-2d04347601b0","sku":"WIDGET-RED","options":[{"name":"Colour","value":"Red"}],"kind":"stocked","priceCents":2495}]},{"productId":"prd_019d4cb8-c230-7235-aee3-dcb05170df0e","title":"Widget twin pack","description":"One blue and one red widget in a gift box.","status":"active","handle":"widget-twin-pack","vendor":"Tidewater Supply Co.","productType":"Widgets","tags":["Hardware","Gift"],"taxClass":"standard","options":[],"variants":[{"variantId":"var_019d4cb8-c618-7383-84f4-8228073621c6","sku":"WIDGET-PAIR","options":[],"kind":"composite","priceCents":4495}]}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The catalog resolved for a channel: its included, non-archived products with their variants and per-SKU prices. This is the shape a channel app's catalog sync, the POS register and the B2B portal consume. An **archived** catalog resolves to its identity and no products — the withdrawal is final, so it is an empty catalog here rather than a 404, and every channel still assigned to it sells nothing. A view holding several catalogs merges them client-side: the union of their products, a SKU priced in several taking the **lowest** price (the catalogs must share a currency for that minimum to mean anything).\n\nRequires `catalogs:read`.","x-mcp-withheld":"a whole catalog with every product and variant in one unpaged answer — megabytes for a large catalog; an agent reads its prices a page at a time with `catalog_list_catalog_prices`","x-required-scopes":["catalogs:read"],"x-example-source":{"origin":"contract"}}},"/settings":{"get":{"tags":["settings"],"operationId":"settings.get","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"StockSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockSettingsEncoded"},"examples":{"contract":{"summary":"settings.get","value":{"transfers":"two-step","homeCurrency":"AUD","homeCurrencyLocked":true,"weightUnit":"kg","lengthUnit":"cm","skuAlphabet":"strict"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's stock policy, home currency (and whether it is settled for good — `homeCurrencyLocked`, once onboarding completes), display units and SKU alphabet. A tenant that has set nothing gets the conservative shape: `transfers: \"two-step\"`, the only mode that never claims stock arrived before it did, `homeCurrency: \"AUD\"`, `weightUnit: \"kg\"`, `lengthUnit: \"cm\"` and `skuAlphabet: \"strict\"`. Read-only.\n\nRequires `settings:read`.","x-mcp-tool":{"name":"inventory_get_settings","title":"Inventory: Get settings","toolset":"locations","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["settings"],"operationId":"settings.set","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"StockSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockSettingsEncoded"},"examples":{"contract":{"summary":"Let each transfer choose its shape, and allow spaces, dots and slashes in SKUs.","value":{"transfers":"unrestricted","homeCurrency":"AUD","homeCurrencyLocked":true,"weightUnit":"kg","lengthUnit":"cm","skuAlphabet":"extended"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"HomeCurrencyLocked | SkuAlphabetInUse | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HomeCurrencyLockedEncoded"},{"$ref":"#/components/schemas/SkuAlphabetInUseEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replace the tenant's stock policy. Every field is optional and falls back to its default, so a partial body is a whole configuration. `transfers` is the shape a transfer takes (`two-step` is the only one that can record a short delivery; `off` allows none). `homeCurrency` (ISO 4217) is what valuation, the ledger and analytics are stated in, and what a new purchase order defaults to; it is settled for good when the tenant's onboarding completes (`homeCurrencyLocked`, `inventory.home-currency-locked`), after which a different one is refused with 409 `HomeCurrencyLocked`. `homeCurrencyLocked` itself is read-only: a value sent here is ignored. `weightUnit` and `lengthUnit` are display only: every figure is stored in grams and millimetres, so changing a unit never changes a SKU. `skuAlphabet` is what a new SKU (an item, a kit) may be made of: `strict` (letters, digits, - and _) or `extended` (also spaces, . and /, for codes a merchant already prints); existing SKUs are never touched, so going back to `strict` is refused with 409 `SkuAlphabetInUse` (naming the SKUs in the way) while any SKU — an item, a variant, a kit — falls outside it. Appends `inventory.settings-configured`. Idempotent by content: the event is a last-write-wins snapshot of the whole policy, so a retry lands on the same settings. **Transfers already open keep the shape they were created under** — changing the policy never reshapes one in flight.\n\nRequires `settings:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockSettingsEncoded"},"example":{"transfers":"unrestricted","homeCurrency":"AUD","weightUnit":"kg","lengthUnit":"cm","skuAlphabet":"extended"}}},"required":true},"x-mcp-tool":{"name":"inventory_set_settings","title":"Inventory: Set settings","toolset":"locations","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}}},"/settings/tax":{"get":{"tags":["settings"],"operationId":"settings.getTax","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"A tenant's tax settings: region and home country, registration number (absent: unregistered, no tax), effective-dated rates per class, the month its financial year starts in, the zone its books keep their days in, the default price convention, and how charges are classed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxSettings"},"examples":{"contract":{"summary":"settings.getTax","value":{"region":"AU-GST","country":"AU","taxNumber":"12 345 678 901","rates":[{"class":"standard","rateBps":1000,"from":"2000-07-01"},{"class":"zero-rated","rateBps":0,"from":"2000-07-01"}],"financialYearStart":7,"timeZone":"Australia/Sydney","defaultConvention":"inclusive","chargeClass":"follows-goods"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's tax settings (`docs/tax.md` › §2): `region` (`AU-GST`, `NZ-GST`, `UK-VAT`, `EU-VAT` or `none`), the home `country`, the registration `taxNumber` (absent: unregistered, so no tax is charged), the effective-dated `rates` per tax class in basis points, the `financialYearStart` (the month its financial year starts in), the `timeZone` its books keep their days in (an accounting period ends at midnight there), the `defaultConvention` a catalog that does not choose states its prices in, and the `chargeClass` shipping and fees are taxed at. A tenant that has set nothing gets `region: \"none\"` — no tax. Read-only.\n\nRequires `settings:read`.","x-mcp-tool":{"name":"inventory_get_tax_settings","title":"Inventory: Tax settings","toolset":"locations","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["settings"],"operationId":"settings.setTax","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"A tenant's tax settings: region and home country, registration number (absent: unregistered, no tax), effective-dated rates per class, the month its financial year starts in, the zone its books keep their days in, the default price convention, and how charges are classed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxSettings"},"examples":{"contract":{"summary":"Register for GST: 10 % on standard goods, shipping taxed as the goods are.","value":{"region":"AU-GST","country":"AU","taxNumber":"12 345 678 901","rates":[{"class":"standard","rateBps":1000,"from":"2000-07-01"},{"class":"zero-rated","rateBps":0,"from":"2000-07-01"}],"financialYearStart":7,"timeZone":"Australia/Sydney","defaultConvention":"inclusive","chargeClass":"follows-goods"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"BasisChangeRefused | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/BasisChangeRefusedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replace the tenant's tax settings with the whole configuration sent. The `country` must be the region's (`AU` for `AU-GST`, `NZ` for `NZ-GST`, `GB` for `UK-VAT`, a member state for `EU-VAT`); `rates` are `{ class, rateBps, from }` rows — the rate in force on a sale's tax point is the row with the latest `from` on or before it — and `zero-rated`, `exempt` and `out-of-scope` carry no rate but 0. Appends `inventory.tax-settings-configured`. Idempotent by content: the event is a last-write-wins snapshot of the whole configuration, and a body equal to the settings in force appends nothing. A rate change applies to documents priced after it; an issued document keeps the rate it was priced at. A `financialYearStart` that would leave a scheduled change of accounting basis (`docs/accounting-basis.md`) off the first day of a financial year is 409 `BasisChangeRefused` (`not-a-year-start`, with the new year's `changeDays`): move or take back the change first. `timeZone` (an IANA name) is where the books keep their days: an accounting period ends at midnight there, and the ledger apps' journals are dated by its days.\n\nRequires `settings:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxSettings"},"example":{"region":"AU-GST","country":"AU","taxNumber":"12 345 678 901","rates":[{"class":"standard","rateBps":1000,"from":"2000-07-01"},{"class":"zero-rated","rateBps":0,"from":"2000-07-01"}],"financialYearStart":7,"timeZone":"Australia/Sydney","defaultConvention":"inclusive","chargeClass":"follows-goods"}}},"required":true},"x-mcp-withheld":"Tax registration and rates decide what every customer is charged: the owner's call in Settings › Tax, where the region's rates are prefilled.","x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}}},"/settings/accounting-basis":{"get":{"tags":["settings"],"operationId":"settings.getAccountingBasis","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"AccountingBasisSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingBasisSettingsEncoded"},"examples":{"contract":{"summary":"settings.getAccountingBasis","value":{"basis":"accrual","booksOpen":true,"financialYearStart":7,"changeDays":["2027-07-01","2028-07-01","2029-07-01"],"schedule":{"opening":"accrual","changes":[]}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The books' accounting basis (`docs/accounting-basis.md`): the `basis` in force today (`accrual` — revenue, expenses and their tax recognised when the invoice or bill is issued — or `cash` — when the money for it moves), the day it took effect (`since`), any change `scheduled`, whether the books are open (`booksOpen`: the opening stocktake is complete), the month the financial year starts in (`financialYearStart`), the `changeDays` a change may take effect from, `changeableFrom` while the last change is under a week old, and the whole `schedule`. Read-only.\n\nRequires `settings:read`.","x-mcp-tool":{"name":"inventory_get_accounting_basis","title":"Inventory: Accounting basis","toolset":"accounting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["settings"],"operationId":"settings.setAccountingBasis","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"AccountingBasisSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingBasisSettingsEncoded"},"examples":{"contract":{"summary":"Move the books to the cash basis from the next financial year.","value":{"basis":"accrual","scheduled":{"basis":"cash","from":"2027-07-01"},"booksOpen":true,"financialYearStart":7,"changeDays":["2027-07-01","2028-07-01","2029-07-01"],"changeableFrom":"2026-10-29T08:30:00.000Z","schedule":{"opening":"accrual","changes":[{"basis":"cash","from":"2027-07-01"}],"changedAt":"2026-10-22T08:30:00.000Z"}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"BasisChangeRefused | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/BasisChangeRefusedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set the books' accounting basis. Before the books open, `basis` alone sets the one they open on. Once they are open, a change is a day in the sand: `from` must be the first day of a coming financial year (the tax settings' `financialYearStart`), after today in the books' zone (its `timeZone`), and from midnight there on that day every posting is made on `basis` — a move to `accrual` recognising, on its day, whatever was still awaiting payment. A change still to come is replaced, and asking for the basis already in force from that day takes it back. Once the books are open the schedule changes at most once a week (`too-soon`, with `changeableFrom`). 409 `BasisChangeRefused` names the `problem` (`day-required`, `day-not-allowed`, `not-a-year-start`, `not-after-today`, `too-soon`) and the `changeDays` allowed. Appends `inventory.accounting-basis-set`. Idempotent by content: a body that leaves the schedule as it is appends nothing.\n\nRequires `settings:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAccountingBasisEncoded"},"example":{"basis":"cash","from":"2027-07-01"}}},"required":true},"x-mcp-withheld":"Moving the books between cash and accrual changes how every later figure is reported: the owner's call in Settings › Tax, from the start of a financial year.","x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}}},"/fx/reference-rate":{"get":{"tags":["fx"],"operationId":"fx.referenceRate","parameters":[{"name":"currency","in":"query","schema":{"$ref":"#/components/schemas/Currency"},"required":true,"example":"USD"},{"name":"date","in":"query","schema":{"$ref":"#/components/schemas/IsoDay"},"required":true,"example":"2026-10-21"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ReferenceRate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceRateEncoded"},"examples":{"contract":{"summary":"US dollars into the home currency (AUD), at the Reserve Bank of Australia's figure.","value":{"currency":"USD","homeCurrency":"AUD","date":"2026-10-21","rate":1.5384,"rateDate":"2026-10-21","source":"rba"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"ReferenceRateUnavailable | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReferenceRateUnavailableEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The published rate converting `currency` into the tenant's home currency on `date` (`YYYY-MM-DD`): `rate` units of the home currency per one unit of `currency`, the central bank's figure for the last day it published on or before `date`, at most a fortnight back. The bank local to the home currency is asked first (the RBA for AUD, the RBNZ for NZD, the ECB for EUR, the Bank of England for GBP, the Fed for USD, the Bank of Canada for CAD, Norges Bank for NOK, Danmarks Nationalbank for DKK); then the ECB, the Fed, the Bank of England, the Bank of Canada, Norges Bank, Danmarks Nationalbank, the RBA and the RBNZ in turn, each directly when the currency is its own or as a cross through it (`via`). `source` and `rateDate` say whose figure and which day; the home currency itself answers rate 1 with no `source`. The rates are the banks' own figures, kept from 1999-12 and refreshed every few hours from Frankfurter's relay of each bank's series; the RBNZ's end 2026-10-15 (its terms forbid automated access), after which NZD converts through the ECB's cross. 409 `ReferenceRateUnavailable` when no bank publishes the currency (`unquoted`) or none did in the fortnight before `date` (`no-rate`). Read-only.\n\nRequires `settings:read`.","x-mcp-withheld":"The services ask it to convert a document in another currency, and each conversion is captured on the document; an agent reads the rate a document used on that document.","x-required-scopes":["settings:read"],"x-example-source":{"origin":"contract"}}},"/views":{"get":{"tags":["views"],"operationId":"views.list","parameters":[{"name":"screen","in":"query","schema":{"$ref":"#/components/schemas/ViewScreen"},"required":false,"example":"inventory"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndexViewEncoded"}},"examples":{"contract":{"summary":"views.list","value":[{"id":"view_019fcab9-8258-728b-aebc-3d12621e3967","screen":"inventory","label":"Main, stock items","query":"","filters":[{"key":"location","operator":"is","values":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]},{"key":"kind","operator":"is","values":["stock"]}],"sort":"sku:asc","createdAt":"2026-08-04T03:03:03.000Z","updatedAt":"2026-08-04T03:03:03.000Z"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's saved list views, label-ascending — one operator's saved search and filters are everyone's. `screen` narrows to one list (`inventory`, `transfers`); the built-in *All* view is never stored and never returned.\n\nRequires `saved-views:read`.","x-mcp-withheld":"Saved list views are the admin's display state (a screen's search and filters), not work; an agent filters the list tools directly.","x-required-scopes":["saved-views:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["views"],"operationId":"views.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"IndexView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexViewEncoded"},"examples":{"contract":{"summary":"views.create","value":{"id":"view_019fcab9-8258-728b-aebc-3d12621e3967","screen":"inventory","label":"Main, stock items","query":"","filters":[{"key":"location","operator":"is","values":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]},{"key":"kind","operator":"is","values":["stock"]}],"sort":"sku:asc","createdAt":"2026-08-04T03:03:03.000Z","updatedAt":"2026-08-04T03:03:03.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Save the current search and filters of a list as a named view. `filters` are the screen's own units — a key, `is`/`is-not`, and the values — stored as given and interpreted by the screen that saved them. Appends `inventory.view-saved`. No idempotency key: a retried save is a second view — accepted, because a view is personal, cheap and deletable, and never touches stock or money.\n\nRequires `saved-views:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveIndexViewEncoded"},"example":{"screen":"inventory","label":"Main, stock items","filters":[{"key":"location","operator":"is","values":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]},{"key":"kind","operator":"is","values":["stock"]}],"sort":"sku:asc"}}},"required":true},"x-mcp-withheld":"Saved list views are the admin's display state (a screen's search and filters), not work; an agent filters the list tools directly.","x-required-scopes":["saved-views:write"],"x-example-source":{"origin":"contract"}}},"/views/{viewId}":{"put":{"tags":["views"],"operationId":"views.update","parameters":[{"name":"viewId","in":"path","schema":{"$ref":"#/components/schemas/ViewId"},"required":true,"example":"view_019fcab9-8258-728b-aebc-3d12621e3967"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"IndexView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexViewEncoded"},"examples":{"contract":{"summary":"Rename the view; its filters stay as they were.","value":{"id":"view_019fcab9-8258-728b-aebc-3d12621e3967","screen":"inventory","label":"Main warehouse stock","query":"","filters":[{"key":"location","operator":"is","values":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]},{"key":"kind","operator":"is","values":["stock"]}],"sort":"sku:asc","createdAt":"2026-08-04T03:03:03.000Z","updatedAt":"2026-10-22T08:40:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ViewNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViewNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Rename a view or replace what it saves; anything omitted stays as it was. Appends `inventory.view-saved` with the whole view. Idempotent by content: the event carries the view entire, so a replay lands on the same view whatever order edits arrived in.\n\nRequires `saved-views:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIndexViewEncoded"},"example":{"label":"Main warehouse stock"}}},"required":true},"x-mcp-withheld":"Saved list views are the admin's display state (a screen's search and filters), not work; an agent filters the list tools directly.","x-required-scopes":["saved-views:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["views"],"operationId":"views.delete","parameters":[{"name":"viewId","in":"path","schema":{"$ref":"#/components/schemas/ViewId"},"required":true,"example":"view_019fcab9-8258-728b-aebc-3d12621e3967"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"IndexView","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexViewEncoded"},"examples":{"contract":{"summary":"views.delete","value":{"id":"view_019fcab9-8258-728b-aebc-3d12621e3967","screen":"inventory","label":"Main, stock items","query":"","filters":[{"key":"location","operator":"is","values":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]},{"key":"kind","operator":"is","values":["stock"]}],"sort":"sku:asc","createdAt":"2026-08-04T03:03:03.000Z","updatedAt":"2026-08-04T03:03:03.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ViewNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViewNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Delete a saved view, answering with the view as it was. Appends `inventory.view-deleted`; a screen showing it falls back to *All*. Idempotent: a retry meets 404 and appends nothing.\n\nRequires `saved-views:write`.","x-mcp-withheld":"Saved list views are the admin's display state (a screen's search and filters), not work; an agent filters the list tools directly.","x-required-scopes":["saved-views:write"],"x-example-source":{"origin":"contract"}}},"/accounts":{"get":{"tags":["accounts"],"operationId":"accounts.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false,"example":"sale"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChartAccountSummaryEncoded"}},"examples":{"contract":{"summary":"accounts.list","value":[{"id":"acct_019cadd3-83c6-7d21-9a4e-6f1b2c3d4e5f","code":"2300","name":"Sales awaiting payment","description":"On the cash basis: invoiced revenue and its tax, until the customer pays for it.","createdAt":"2026-03-02T09:14:06.150Z","updatedAt":"2026-03-02T09:14:06.150Z","skus":0,"defaultFor":["sales-awaiting-payment"]},{"id":"acct_019cadd3-83f8-7b89-810d-568f90349401","code":"4000","name":"Sales","description":"Income from goods and services sold.","createdAt":"2026-03-02T09:14:06.200Z","updatedAt":"2026-03-02T09:14:06.200Z","skus":4,"defaultFor":["revenue"]},{"id":"acct_01a161c4-0a00-72db-a577-07bcb2a24026","code":"4010","name":"Wholesale sales","description":"Income from trade customers.","createdAt":"2026-10-22T04:00:00.000Z","updatedAt":"2026-10-22T04:00:00.000Z","skus":0,"defaultFor":[]},{"id":"acct_019cadd3-845c-7876-813d-b58885d7fa14","code":"5000","name":"Cost of sales","description":"The cost of the stock consumed by a sale.","createdAt":"2026-03-02T09:14:06.300Z","updatedAt":"2026-03-02T09:14:06.300Z","skus":4,"defaultFor":["expense"]}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's chart of accounts in natural code order (`90`, `200`, `1400`), each with what holds it in place: `skus`, how many SKUs post to it in any role, and `defaultFor`, the roles it is the tenant default for (1400 inventory, 4000 revenue, 5000 expense). An account a ledger app keeps carries `managedBy` (the app and its own id for the account) and, when the app archived it, `archived`. `q` narrows to accounts whose code or name contains it. Never empty: every organization is provisioned with the default accounts.\n\nRequires `financials:read` or `settings:read`.","x-mcp-tool":{"name":"accounting_list_accounts","title":"Accounting: List accounts","toolset":"accounting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["financials:read","settings:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["accounts"],"operationId":"accounts.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"ChartAccount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartAccountEncoded"},"examples":{"contract":{"summary":"accounts.create","value":{"id":"acct_01a161c4-0a00-72db-a577-07bcb2a24026","code":"4010","name":"Wholesale sales","description":"Income from trade customers.","createdAt":"2026-10-22T04:00:00.000Z","updatedAt":"2026-10-22T04:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"AccountCodeConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AccountCodeConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Add an account to the chart, kept by the tenant. Codes are text (a whole number is read as its digits), unique within the tenant — 409 `AccountCodeConflict` if one already answers to it. Appends `inventory.account-saved`. Needs the `admin` job. Idempotent on the code: a retried create meets 409 `AccountCodeConflict`, never a second account.\n\nRequires `settings:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChartAccountEncoded"},"example":{"code":"4010","name":"Wholesale sales","description":"Income from trade customers."}}},"required":true},"x-mcp-tool":{"name":"accounting_create_account","title":"Accounting: Create account","toolset":"accounting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}}},"/accounts/{accountId}":{"put":{"tags":["accounts"],"operationId":"accounts.update","parameters":[{"name":"accountId","in":"path","schema":{"$ref":"#/components/schemas/AcctId"},"required":true,"example":"acct_01a161c4-0a00-72db-a577-07bcb2a24026"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ChartAccount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartAccountEncoded"},"examples":{"contract":{"summary":"Reword the account's description; its code and name stay.","value":{"id":"acct_01a161c4-0a00-72db-a577-07bcb2a24026","code":"4010","name":"Wholesale sales","description":"Income from trade customers on account.","createdAt":"2026-10-22T04:00:00.000Z","updatedAt":"2026-10-22T08:50:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChartAccountNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartAccountNotFoundEncoded"}}}},"409":{"description":"AccountCodeConflict | AccountInUse | DefaultAccountProtected | AccountManagedByApp | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AccountCodeConflictEncoded"},{"$ref":"#/components/schemas/AccountInUseEncoded"},{"$ref":"#/components/schemas/DefaultAccountProtectedEncoded"},{"$ref":"#/components/schemas/AccountManagedByAppEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Retitle, describe or renumber an account; anything omitted stays as it was. A code change is refused with 409 `AccountInUse` while any SKU posts to the account (its SKUs store the code), and with 409 `DefaultAccountProtected` for a role's default account, and with 409 `AccountManagedByApp` for an account a ledger app keeps (it is changed there and synced here). Appends `inventory.account-saved` with the whole account. Needs the `admin` job. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `settings:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChartAccountEncoded"},"example":{"description":"Income from trade customers on account."}}},"required":true},"x-mcp-tool":{"name":"accounting_update_account","title":"Accounting: Update account","toolset":"accounting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["accounts"],"operationId":"accounts.delete","parameters":[{"name":"accountId","in":"path","schema":{"$ref":"#/components/schemas/AcctId"},"required":true,"example":"acct_01a161c4-0a00-72db-a577-07bcb2a24026"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ChartAccount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartAccountEncoded"},"examples":{"contract":{"summary":"accounts.delete","value":{"id":"acct_01a161c4-0a00-72db-a577-07bcb2a24026","code":"4010","name":"Wholesale sales","description":"Income from trade customers.","createdAt":"2026-10-22T04:00:00.000Z","updatedAt":"2026-10-22T04:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChartAccountNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartAccountNotFoundEncoded"}}}},"409":{"description":"AccountInUse | DefaultAccountProtected | AccountManagedByApp | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AccountInUseEncoded"},{"$ref":"#/components/schemas/DefaultAccountProtectedEncoded"},{"$ref":"#/components/schemas/AccountManagedByAppEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Remove an account from the chart, answering with the account as it was. Refused with 409 `AccountInUse` while any SKU posts to it and 409 `DefaultAccountProtected` for a role's default account — an account in use is never removed — and 409 `AccountManagedByApp` for one a ledger app keeps. Appends `inventory.account-deleted`. Needs the `admin` job. Idempotent: a retry meets 404 and appends nothing.\n\nRequires `settings:write`.","x-mcp-tool":{"name":"accounting_delete_account","title":"Accounting: Delete account","toolset":"accounting","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["settings:write"],"x-example-source":{"origin":"contract"}}},"/accounts/managed":{"put":{"tags":["accounts"],"operationId":"accounts.syncManaged","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ManagedAccountsSync","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountsSyncEncoded"},"examples":{"contract":{"summary":"A ledger app reports its chart: one account new, one matching a code the tenant has, one Manifold cannot hold.","value":{"results":[{"externalId":"01a15890-7dea-7806-9cf0-c59f91669602","code":"4020","outcome":"created","accountId":"acct_019e80e8-c900-79a0-be53-3d5443d6d0a2"},{"externalId":"01a1589d-8690-7b74-aefc-712fb1b0fec2","code":"4010","outcome":"claimed","accountId":"acct_01a161c4-0a00-72db-a577-07bcb2a24026"},{"externalId":"01a15860-14a6-74e8-9328-26df4b457cba","code":"BANK FEES","outcome":"skipped","reason":"the code \"BANK FEES\" is not one the chart can hold (letters and digits, up to 20 characters)"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"NotALedgerApp | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NotALedgerAppEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A ledger app (Xero, MYOB) reports its chart of accounts, whole, under its own token (403 `NotALedgerApp` for anyone else), and the tenant's chart follows it (`docs/chart-of-accounts.md`). An account the app already keeps is found by its `externalId` and renamed, renumbered or archived to match; one at a code the tenant already has is `claimed` — kept from then on by the app; any other is `created`. Nothing is ever removed: an account the app keeps that its chart no longer lists is marked `archived`, and the tenant's own accounts are left alone. An account is `skipped`, with a `reason`, when its code is one Manifold cannot hold, another app keeps that code, or SKUs or a default stand in the way of renumbering it. Appends `inventory.account-saved` per account that changed. Idempotent by content: a chart reported as it already stands appends nothing.\n\nRequires `financials:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncManagedAccountsEncoded"},"example":{"accounts":[{"externalId":"01a15890-7dea-7806-9cf0-c59f91669602","code":"4020","name":"Online sales","archived":false},{"externalId":"01a1589d-8690-7b74-aefc-712fb1b0fec2","code":"4010","name":"Wholesale sales","description":"Income from trade customers.","archived":false},{"externalId":"01a15860-14a6-74e8-9328-26df4b457cba","code":"BANK FEES","name":"Bank fees","archived":false}]}}},"required":true},"x-mcp-withheld":"only a ledger app's own token may report its chart (NotALedgerApp for anyone else); an agent connects Xero or MYOB and asks for a sync instead","x-required-scopes":["financials:write"],"x-example-source":{"origin":"contract"}}},"/accounts/managed/release":{"post":{"tags":["accounts"],"operationId":"accounts.releaseManaged","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ManagedAccountsReleased","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountsReleasedEncoded"},"examples":{"contract":{"summary":"The ledger was disconnected: the accounts it kept are the tenant's again.","value":{"released":["acct_019e80e8-c900-79a0-be53-3d5443d6d0a2","acct_01a161c4-0a00-72db-a577-07bcb2a24026"]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"NotALedgerApp | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NotALedgerAppEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A ledger app lets go of every account it keeps — when its ledger is disconnected — under its own token (403 `NotALedgerApp` for anyone else). The accounts stay, as they last were, kept by the tenant again and editable here. An uninstalled app's accounts are let go by the core itself, on `auth.app-uninstalled`. Appends `inventory.account-saved` per account released. Idempotent by state: an app that keeps nothing appends nothing.\n\nRequires `financials:write`.","x-mcp-withheld":"only a ledger app's own token lets go of its accounts; disconnecting or uninstalling the app does it, from the app's page in the admin","x-required-scopes":["financials:write"],"x-example-source":{"origin":"contract"}}},"/accounts/managed/sync":{"post":{"tags":["accounts"],"operationId":"accounts.requestSync","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ChartSyncRequested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartSyncRequestedEncoded"},"examples":{"contract":{"summary":"accounts.requestSync","value":{"appIds":["app_019b8b74-1be8-706f-8b57-e56e7d3c0d9d"]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"ChartNotManaged | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChartNotManagedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Ask the ledger apps that keep any of the chart to sync it now — the Sync button under Settings › Chart of accounts. The webhooks service tells each (`chart.sync-requested`), and its sync lands as `PUT /accounts/managed` in its own time; read the chart again to see it. 409 `ChartNotManaged` while no app keeps an account. Appends `inventory.chart-sync-requested`. No idempotency key: each press asks the apps again, and a sync that finds the chart as it stands appends nothing, so a repeated ask changes nothing twice.\n\nRequires `settings:write` or `financials:write`.","x-mcp-tool":{"name":"accounting_sync_chart","title":"Accounting: Sync chart","toolset":"accounting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},"x-required-scopes":["settings:write","financials:write"],"x-example-source":{"origin":"contract"}}},"/channels":{"get":{"tags":["channels"],"operationId":"channels.list","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ChannelList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelListEncoded"},"examples":{"contract":{"summary":"channels.list","value":{"items":[{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"connected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-03-12T07:00:02.000Z"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's sales channels — every place it sells, whatever app provides it: each with its `type` (the slug its app declares), its own `externalId` (the account in the channel's own system), whether it is connected, the catalogs it publishes and where, the link to open one of its orders and the admin path its app configures it at (`settingsPath`). Connected channels first, then by name.\n\nRequires `integrations:read` or `catalogs:read` or `orders:read`.","x-mcp-tool":{"name":"inventory_list_channels","title":"Inventory: List channels","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["integrations:read","catalogs:read","orders:read"],"x-example-source":{"origin":"contract"}}},"/channels/{channelId}":{"get":{"tags":["channels"],"operationId":"channels.get","parameters":[{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelEncoded"},"examples":{"contract":{"summary":"channels.get","value":{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"connected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-03-12T07:00:02.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChannelNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One sales channel, connected or not: what kind it is, the place it is (a shop domain), the catalogs it publishes and where, and the link to open one of its orders — what an order's `source.channelId` names. 404 `ChannelNotFound`.\n\nRequires `integrations:read` or `catalogs:read` or `orders:read`.","x-mcp-tool":{"name":"inventory_get_channel","title":"Inventory: Get channel","toolset":"catalog","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["integrations:read","catalogs:read","orders:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["channels"],"operationId":"channels.connect","parameters":[{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelEncoded"},"examples":{"contract":{"summary":"The web store's app connects its store, publishing the Default catalog.","value":{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"connected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-03-12T07:00:02.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ChannelNotYours | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChannelNotYoursEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"ChannelConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChannelConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Connect a sales channel, or say what a connected one is now — the call the app providing the channel makes when a store is connected and whenever its name, its catalogs, its order link, its settings page (`settingsPath`, a path in the admin) or the currency it sells in (`currency`, ISO 4217) change. The app mints `channelId` (`chn_…`) and sends the whole description: `type` and `externalId` say which place it is and are fixed once connected; `catalogs` lists the catalogs it publishes, each at one of the channel's own targets. Appends `inventory.channel-connected` for a new or disconnected channel and `inventory.channel-updated` naming only what changed for a connected one. 409 `ChannelConflict` when another connected channel already is this `type` and `externalId`, or when the body would change what an existing channel is; 404 `CatalogNotFound` for a catalog the tenant does not have. Only an app's own token connects a channel, and the channel records that app as its `appId` (from the token, never the body; fixed once connected): 403 `ChannelNotYours` for a person's token, for a channel another app provides, or for a `type` that is not the app's — one of Manifold's apps connects only the type its catalogue entry declares, and no other app connects that type. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `integrations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectChannelEncoded"},"example":{"type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD"}}},"required":true},"x-mcp-withheld":"Called by the app that provides the channel whenever the channel connects or what it publishes changes; an agent connects a store by installing the app and maps its catalogs with the app's own connection tool.","x-required-scopes":["integrations:write"],"x-example-source":{"origin":"contract"}}},"/channels/{channelId}/intake":{"put":{"tags":["channels"],"operationId":"channels.reportIntake","parameters":[{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelEncoded"},"examples":{"contract":{"summary":"The web store's app says two of its orders could not be brought in.","value":{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"connected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-10-22T09:00:00.000Z","intake":{"importing":false,"notBroughtIn":2,"reportedAt":"2026-10-22T09:00:00.000Z"}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ChannelNotYours | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChannelNotYoursEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChannelNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Say how a channel's orders are coming in — the call the app providing the channel makes as that changes: whether it is still bringing the channel's existing orders across (`importing`), and how many orders the channel sent that it could not create in Manifold (`notBroughtIn`, each listed with its reason and a retry on the app's own page at the channel's `settingsPath`). The channel answers it as `intake`, which the Orders screen shows. Only the app providing the channel reports, under its own token: 403 `ChannelNotYours` for a person's token or another app's; 404 `ChannelNotFound`. Appends `inventory.channel-intake-reported`. Idempotent by content: a report that changes nothing is acknowledged and appends nothing.\n\nRequires `integrations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportChannelIntakeEncoded"},"example":{"importing":false,"notBroughtIn":2}}},"required":true},"x-mcp-withheld":"Called by the app that provides the channel as its orders come in or are refused; an agent reads the channel's intake with inventory_list_channels and a store's refused orders with the app's own tools.","x-required-scopes":["integrations:write"],"x-example-source":{"origin":"contract"}}},"/channels/{channelId}/attention":{"put":{"tags":["channels"],"operationId":"channels.reportAttention","parameters":[{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelEncoded"},"examples":{"contract":{"summary":"The web store's app says the store must re-approve a permission.","value":{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"connected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-10-22T09:00:00.000Z","attention":{"items":[{"kind":"reconsent","severity":"warning","message":"Needs re-approving for its payouts","link":"/apps/store/stores/conn_1"}],"reportedAt":"2026-10-22T09:00:00.000Z"}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ChannelNotYours | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChannelNotYoursEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChannelNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Say what about a channel needs a person's attention — the call the app providing the channel makes as that changes: the whole list (`items`, at most 20; empty when nothing does), each a `kind` the app declares, a `severity` (`critical`, `warning`), the `message` in the merchant's words and the admin `link` where it is sorted (its app's page; the channel's `settingsPath` when absent). The channel answers it as `attention`, which the home dashboard shows for any app. Only the app providing the channel reports, under its own token: 403 `ChannelNotYours` for a person's token or another app's; 404 `ChannelNotFound`. Appends `inventory.channel-attention-reported`. Idempotent by content: a report that changes nothing is acknowledged and appends nothing.\n\nRequires `integrations:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportChannelAttentionEncoded"},"example":{"items":[{"kind":"reconsent","severity":"warning","message":"Needs re-approving for its payouts","link":"/apps/store/stores/conn_1"}]}}},"required":true},"x-mcp-withheld":"Called by the app that provides the channel as what needs looking at changes; an agent reads a channel's attention with inventory_list_channels and acts on it through the app's own tools.","x-required-scopes":["integrations:write"],"x-example-source":{"origin":"contract"}}},"/channels/{channelId}/disconnect":{"post":{"tags":["channels"],"operationId":"channels.disconnect","parameters":[{"name":"channelId","in":"path","schema":{"$ref":"#/components/schemas/ChnId"},"required":true,"example":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelEncoded"},"examples":{"contract":{"summary":"channels.disconnect","value":{"id":"chn_019ce0d8-5d50-7597-8115-9ea4c1b646da","appId":"app_019b8b74-1800-79fd-be5b-3df405745c4d","type":"webstore","externalId":"tidewater-supply.example","name":"Tidewater online store","status":"disconnected","catalogs":[{"catalogId":"cat_019cadd3-8524-7934-9ee3-29b896f71f80","externalId":"online-store","externalName":"Online Store"}],"orderUrl":"https://tidewater-supply.example/admin/orders/{externalId}","settingsPath":"/settings/channels/webstore","currency":"AUD","connectedAt":"2026-03-12T07:00:02.000Z","createdAt":"2026-03-12T07:00:02.000Z","updatedAt":"2026-10-22T09:00:00.000Z","disconnectedAt":"2026-10-22T09:00:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ChannelNotYours | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChannelNotYoursEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ChannelNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Disconnect a sales channel — its app let it go: the store uninstalled, the account closed. Its history and orders stay; its location bindings stop holding their sites; connecting it again (`PUT /channels/:channelId`) restores it. A person may let any of the business's channels go; an app only one it provides (403 `ChannelNotYours`). Appends `inventory.channel-disconnected`. Idempotent by state: a channel already disconnected is acknowledged and appends nothing.\n\nRequires `integrations:write`.","x-mcp-withheld":"Called by the app that provides the channel when the store uninstalls it or the connection is deleted — disconnecting a store is the merchant's call in Settings › Sales channels, not an agent's.","x-required-scopes":["integrations:write"],"x-example-source":{"origin":"contract"}}},"/sources":{"get":{"tags":["sources"],"operationId":"sources.list","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"SourceList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceListEncoded"},"examples":{"contract":{"summary":"sources.list","value":{"items":[{"sourceId":"src_019cb5dc-bf88-756c-8d01-2fa61dd4b669","appId":"app_019b8b74-1fd0-7d77-ba23-1c91bb26607d","type":"legacy-erp","name":"Previous ERP","status":"mirroring","importedAt":"2026-03-04T01:12:40.000Z","counts":[{"kind":"products","count":412},{"kind":"locations","count":2},{"kind":"parties","count":1380},{"kind":"stock-positions","count":824}],"connectedAt":"2026-03-03T22:41:09.000Z","updatedAt":"2026-03-04T01:12:40.000Z"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's legacy sources — the platforms it is migrating from (an ERP or inventory system it is leaving), whatever app provides each: its `type` (a slug the app declares), the app that provides it, where the migration stands (`connected`, `importing`, `mirroring`, `retired`), when the first import landed (`importedAt`) and what it brought, per kind (`counts`). Live sources first, then by name. What the onboarding walk and Settings read to say what an import covered.\n\nRequires `imports:read` or `integrations:read` or `setup:read`.","x-mcp-tool":{"name":"inventory_list_sources","title":"Inventory: List sources","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read","integrations:read","setup:read"],"x-example-source":{"origin":"contract"}}},"/sources/{sourceId}":{"put":{"tags":["sources"],"operationId":"sources.describe","parameters":[{"name":"sourceId","in":"path","schema":{"$ref":"#/components/schemas/SrcId"},"required":true,"example":"src_019cb5dc-bf88-756c-8d01-2fa61dd4b669"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceEncoded"},"examples":{"contract":{"summary":"The source's app reports its first import has landed and the tenant now mirrors it.","value":{"sourceId":"src_019cb5dc-bf88-756c-8d01-2fa61dd4b669","appId":"app_019b8b74-1fd0-7d77-ba23-1c91bb26607d","type":"legacy-erp","name":"Previous ERP","status":"mirroring","importedAt":"2026-03-04T01:12:40.000Z","counts":[{"kind":"products","count":412},{"kind":"locations","count":2},{"kind":"parties","count":1380},{"kind":"stock-positions","count":824}],"connectedAt":"2026-03-03T22:41:09.000Z","updatedAt":"2026-03-04T01:12:40.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"SourceNotYours | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SourceNotYoursEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"SourceAlreadyRetired | SourceConflict | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SourceAlreadyRetiredEncoded"},{"$ref":"#/components/schemas/SourceConflictEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Register a legacy source, or say where it stands now — the call the app providing the source makes, under its own token, when it connects to the platform, as its first import runs and lands, and when its installation is retired at go-live. The app mints `sourceId` (`src_…`) and sends the whole description: `type` is fixed once registered; `status` and `counts` are the migration as it stands. The registry stamps `importedAt` the first time the source reaches `mirroring`; the app never sends it. Appends `inventory.source-connected` for a new source and `inventory.source-updated` naming only what changed for a known one. 403 `SourceNotYours` for anyone but an app whose first-party role is `legacy-platform` (a sales channel holding `imports:write` included), or for a source another app registered; 409 `SourceConflict` when the body would change the source's `type`; 409 `SourceAlreadyRetired` for any change to a retired source. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DescribeSourceEncoded"},"example":{"type":"legacy-erp","name":"Previous ERP","status":"mirroring","counts":[{"kind":"products","count":412},{"kind":"locations","count":2},{"kind":"parties","count":1380},{"kind":"stock-positions","count":824}]}}},"required":true},"x-mcp-withheld":"Called only by the app that provides the legacy source (a legacy-platform app), under its own token, as its import runs and at go-live — the endpoint refuses any other caller; an agent reads where a migration stands with inventory_list_sources.","x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/transfers":{"get":{"tags":["transfers"],"operationId":"transfers.list","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"required":false},{"name":"status","in":"query","schema":{"type":"string"},"required":false,"example":"draft,in-transit"},{"name":"sort","in":"query","schema":{"$ref":"#/components/schemas/TransferSortKey"},"required":false},{"name":"order","in":"query","schema":{"$ref":"#/components/schemas/SortOrder"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"25"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"TransferPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPageEncoded"},"examples":{"contract":{"summary":"transfers.list","value":{"items":[{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"in-transit","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":6,"received":0}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-21T00:40:00.000Z"}],"total":1,"limit":25,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the tenant's stock transfers, newest first. `q` is a case-insensitive substring of the transfer id, its number (`TR-00042`) or its reference, `status` narrows to one point of the lifecycle, and `total` counts everything matching the query regardless of `limit`/`offset`.\n\nRequires `stock:read`.","x-mcp-tool":{"name":"inventory_list_transfers","title":"Inventory: List transfers","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["transfers"],"operationId":"transfers.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEncoded"},"examples":{"contract":{"summary":"Open a two-step transfer of six blue widgets from Main to the shopfront.","value":{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"draft","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":0,"received":0}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-21T00:15:27.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound | ItemNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationNotFoundEncoded"},{"$ref":"#/components/schemas/ItemNotFoundEncoded"}]}}}},"409":{"description":"LocationArchived | TransfersDisabled | TransferModeNotAllowed | InsufficientStock | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/TransfersDisabledEncoded"},{"$ref":"#/components/schemas/TransferModeNotAllowedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Open a transfer between two of the tenant's own locations. **What this does depends on the tenant's transfer policy** (see `GET /settings`). Under `two-step` it opens the document and moves nothing until despatch, appending `inventory.transfer-created`. Under `instant` the entire move happens here in one commit with no in-transit state — appending `inventory.transfer-completed`, a single fact, because an instant transfer never *was* in transit and recording a despatch followed by a receipt would describe a moment that did not happen. Under `unrestricted` the caller picks with `mode`; asking for a shape the policy forbids is 409 `TransferModeNotAllowed` rather than being quietly corrected, and 409 `TransfersDisabled` when the policy is `off`. An instant transfer checks free stock at the source up front (409 `InsufficientStock`), because it is moving it now. A transfer *into* a non-fulfillable site is entirely normal: that is how stock reaches a quarantine bay. `reference` is required and is the idempotency key: a retry with the same reference is acknowledged with the transfer it already opened — under `instant`, the units move once.\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransferEncoded"},"example":{"fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","mode":"two-step","reference":"restock-shopfront-2026-10-21","lines":[{"sku":"WIDGET-BLUE","quantity":6}]}}},"required":true},"x-mcp-tool":{"name":"inventory_create_transfer","title":"Inventory: Create transfer","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/transfers/{transferId}":{"get":{"tags":["transfers"],"operationId":"transfers.get","parameters":[{"name":"transferId","in":"path","schema":{"$ref":"#/components/schemas/TrfId"},"required":true,"example":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEncoded"},"examples":{"contract":{"summary":"transfers.get","value":{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"in-transit","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":6,"received":0}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-21T00:40:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"TransferNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One transfer, with per-line `quantity`, `despatched` and `received`. The gap between the last two is what is still on the road.\n\nRequires `stock:read`.","x-mcp-tool":{"name":"inventory_get_transfer","title":"Inventory: Get transfer","toolset":"stock","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read"],"x-example-source":{"origin":"contract"}}},"/transfers/{transferId}/despatch":{"post":{"tags":["transfers"],"operationId":"transfers.despatch","parameters":[{"name":"transferId","in":"path","schema":{"$ref":"#/components/schemas/TrfId"},"required":true,"example":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEncoded"},"examples":{"contract":{"summary":"transfers.despatch","value":{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"in-transit","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":6,"received":0}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-21T00:40:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"TransferNotFound | ItemNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TransferNotFoundEncoded"},{"$ref":"#/components/schemas/ItemNotFoundEncoded"}]}}}},"409":{"description":"TransferNotInState | TransferQuantityExceeded | TransferModeNotAllowed | InsufficientStock | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TransferNotInStateEncoded"},{"$ref":"#/components/schemas/TransferQuantityExceededEncoded"},{"$ref":"#/components/schemas/TransferModeNotAllowedEncoded"},{"$ref":"#/components/schemas/InsufficientStockEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Send the transfer on its way. Units come off the source's shelf and land in the destination's `inTransit` — sellable at neither end, which is the honest position for stock in a van. Omit `lines` to send everything outstanding, or name them to send part. The source must hold what is being sent *free* (409 `InsufficientStock` counts reserved units as unavailable — they are promised to an order). Appends `inventory.transfer-despatched`. `reference` is required and is the idempotency key: a retry with the same reference is acknowledged and appends nothing — which is what makes a partial despatch safe to resend.\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DespatchTransferEncoded"},"example":{"reference":"TR-00042-despatch-1"}}},"required":true},"x-mcp-tool":{"name":"inventory_despatch_transfer","title":"Inventory: Despatch transfer","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/transfers/{transferId}/receive":{"post":{"tags":["transfers"],"operationId":"transfers.receive","parameters":[{"name":"transferId","in":"path","schema":{"$ref":"#/components/schemas/TrfId"},"required":true,"example":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEncoded"},"examples":{"contract":{"summary":"Five of the six arrive; the sixth stays in transit.","value":{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"in-transit","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":6,"received":5}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-22T23:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"TransferNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferNotFoundEncoded"}}}},"409":{"description":"TransferNotInState | TransferQuantityExceeded | TransferModeNotAllowed | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TransferNotInStateEncoded"},{"$ref":"#/components/schemas/TransferQuantityExceededEncoded"},{"$ref":"#/components/schemas/TransferModeNotAllowedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Book in what actually turned up: `inTransit` falls and on-hand rises at the destination. Omit `lines` to receive everything on the road; name fewer to record a short delivery, which leaves the remainder in transit for a later receipt or a cancellation rather than quietly evaporating. The transfer settles to `received` only when nothing is still out. Appends `inventory.transfer-received`. `reference` is required and is the idempotency key: a retry with the same reference is acknowledged and appends nothing — which is what makes a short receipt safe to resend.\n\nRequires `stock:write` or `receiving:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveTransferEncoded"},"example":{"lines":[{"sku":"WIDGET-BLUE","quantity":5}],"reference":"TR-00042-receipt-1"}}},"required":true},"x-mcp-tool":{"name":"inventory_receive_transfer","title":"Inventory: Receive transfer","toolset":"stock","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","receiving:write"],"x-example-source":{"origin":"contract"}}},"/transfers/{transferId}/cancel":{"post":{"tags":["transfers"],"operationId":"transfers.cancel","parameters":[{"name":"transferId","in":"path","schema":{"$ref":"#/components/schemas/TrfId"},"required":true,"example":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEncoded"},"examples":{"contract":{"summary":"Cancel after a short receipt: the unit still in transit goes back to Main.","value":{"id":"trf_01a15bd0-1918-7e9f-bf21-92e337bede18","number":"TR-00042","fromLocationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","toLocationId":"loc_019cd06e-3b38-7e92-b496-c92f8184a3aa","status":"cancelled","mode":"two-step","lines":[{"sku":"WIDGET-BLUE","quantity":6,"despatched":5,"received":5}],"reference":"restock-shopfront-2026-10-21","createdAt":"2026-10-21T00:15:27.000Z","updatedAt":"2026-10-22T23:20:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"TransferNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferNotFoundEncoded"}}}},"409":{"description":"TransferNotInState | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TransferNotInStateEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Withdraw the transfer. Anything still in transit returns to the source rather than vanishing — a cancelled van still has stock in it. 409 `TransferNotInState` once it has been fully received; Appends `inventory.transfer-cancelled`. Idempotent by state: a transfer is cancelled once, so a retry on a cancelled transfer is acknowledged and appends nothing (a second `reason` is ignored).\n\nRequires `stock:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelTransferEncoded"},"example":{"reason":"Sixth unit stayed on the van; it goes back to Main."}}},"required":true},"x-mcp-tool":{"name":"inventory_cancel_transfer","title":"Inventory: Cancel transfer","toolset":"stock","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/stocktakes":{"get":{"tags":["stocktakes"],"operationId":"stocktakes.list","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"StocktakeList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeListEncoded"},"examples":{"contract":{"summary":"stocktakes.list","value":{"items":[{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"open","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counted":2,"costed":0,"startedAt":"2026-10-22T21:30:00.000Z"},{"id":"stk_019ceaee-1f00-71ce-a539-8c15e4cefde0","number":"ST-00001","kind":"opening","status":"completed","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","loc_019cd06e-3b38-7e92-b496-c92f8184a3aa"],"counted":4,"costed":2,"startedAt":"2026-03-14T06:00:00.000Z","completedAt":"2026-03-14T09:45:00.000Z"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Every stocktake the tenant has started, newest first, each with how far it got (`counted` pairs, `costed` SKUs). The tenant's first completed one is its `opening` stocktake, where the general ledger begins (`docs/stocktake.md`); a tenant with no completed `opening` stocktake has no general ledger yet, and no ledger app can be activated.\n\nRequires `stock:read`.","x-mcp-tool":{"name":"inventory_list_stocktakes","title":"Inventory: List stocktakes","toolset":"stocktakes","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["stocktakes"],"operationId":"stocktakes.start","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Stocktake","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeEncoded"},"examples":{"contract":{"summary":"Start a periodic count of Main; the caller mints the stocktake's id.","value":{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"open","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counts":[],"costs":[],"startedAt":"2026-10-22T21:30:00.000Z","updatedAt":"2026-10-22T21:30:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"LocationNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNotFoundEncoded"}}}},"409":{"description":"StocktakeInProgress | StocktakeLineRefused | LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StocktakeInProgressEncoded"},{"$ref":"#/components/schemas/StocktakeLineRefusedEncoded"},{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Start a stocktake, appending `inventory.stocktake-started`. The tenant's first (after any it cancelled) is its `opening` stocktake: it counts every live location (naming fewer is 409 `StocktakeLineRefused`) and values every stock SKU, and completing it opens the general ledger (`docs/stocktake.md`). Every later one is `periodic`, over the `locationIds` it names (all live locations when omitted). One is open at a time: 409 `StocktakeInProgress` names the open one. Moving nothing until it completes, it is open to a person while the tenant's stock is mirrored from a source, and to anyone holding `financials:write` — the count is stock's, the values the books'. `stocktakeId` is the caller-minted `stk_` id and the idempotency key: a retry with the same `stocktakeId` is acknowledged with the stocktake it started and appends nothing.\n\nRequires `stock:write` or `financials:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartStocktakeEncoded"},"example":{"stocktakeId":"stk_01a16585-57c0-7200-961d-25255f868ed4","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"]}}},"required":true},"x-mcp-tool":{"name":"inventory_start_stocktake","title":"Inventory: Start stocktake","toolset":"stocktakes","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","financials:write"],"x-example-source":{"origin":"contract"}}},"/stocktakes/{stocktakeId}":{"get":{"tags":["stocktakes"],"operationId":"stocktakes.get","parameters":[{"name":"stocktakeId","in":"path","schema":{"$ref":"#/components/schemas/StkId"},"required":true,"example":"stk_01a16585-57c0-7200-961d-25255f868ed4"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Stocktake","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeEncoded"},"examples":{"contract":{"summary":"stocktakes.get","value":{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"open","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counts":[{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":137},{"sku":"WIDGET-RED","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":0}],"costs":[],"startedAt":"2026-10-22T21:30:00.000Z","updatedAt":"2026-10-22T21:55:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"StocktakeNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One stocktake with every count (per SKU and location) and cost (per SKU) entered so far; once `completed`, the counts are what it set the stock to.\n\nRequires `stock:read`.","x-mcp-tool":{"name":"inventory_get_stocktake","title":"Inventory: Get stocktake","toolset":"stocktakes","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read"],"x-example-source":{"origin":"contract"}}},"/stocktakes/{stocktakeId}/sheet":{"get":{"tags":["stocktakes"],"operationId":"stocktakes.sheet","parameters":[{"name":"stocktakeId","in":"path","schema":{"$ref":"#/components/schemas/StkId"},"required":true,"example":"stk_01a16585-57c0-7200-961d-25255f868ed4"},{"name":"q","in":"query","schema":{"type":"string"},"required":false},{"name":"missingCost","in":"query","schema":{"$ref":"#/components/schemas/BooleanString"},"required":false},{"name":"locationId","in":"query","schema":{"$ref":"#/components/schemas/LocId"},"required":false},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"100"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"StocktakeSheet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeSheetEncoded"},"examples":{"contract":{"summary":"stocktakes.sheet","value":{"stocktakeId":"stk_01a16585-57c0-7200-961d-25255f868ed4","kind":"periodic","status":"open","lines":[{"sku":"WIDGET-BLUE","name":"Widget, blue","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","expected":140,"counted":137,"suggestedCostCents":1250,"missingCost":false},{"sku":"WIDGET-GREEN","name":"Widget, green","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","expected":0,"missingCost":false},{"sku":"WIDGET-RED","name":"Widget, red","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","expected":0,"counted":0,"suggestedCostCents":1250,"missingCost":false},{"sku":"WIDGET-SERIAL","name":"Widget controller, serialised","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","expected":7,"suggestedCostCents":8900,"missingCost":false}],"total":4,"missingCosts":0,"limit":100,"offset":0}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"StocktakeNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The counting sheet: every (SKU, location) of the stocktake's scope that holds stock or was counted, and every stock SKU at least once, with `expected` (what inventory holds there now), the `counted` figure, the SKU's `unitCostCents` and, where it has none, the `suggestedCostCents` its cost basis offers. `missingCost` marks a SKU an opening stocktake cannot complete without (no cost on it and no cost basis); `missingCosts` counts them all. `q` narrows by SKU or name, `missingCost=true` to the SKUs still to value; paged by `limit` (1–500, 100 when omitted) and `offset`, `total` counting every match.\n\nRequires `stock:read`.","x-mcp-tool":{"name":"inventory_stocktake_sheet","title":"Inventory: Stocktake counting sheet","toolset":"stocktakes","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:read"],"x-example-source":{"origin":"contract"}}},"/stocktakes/{stocktakeId}/counts":{"put":{"tags":["stocktakes"],"operationId":"stocktakes.counts","parameters":[{"name":"stocktakeId","in":"path","schema":{"$ref":"#/components/schemas/StkId"},"required":true,"example":"stk_01a16585-57c0-7200-961d-25255f868ed4"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Stocktake","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeEncoded"},"examples":{"contract":{"summary":"stocktakes.counts","value":{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"open","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counts":[{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":137},{"sku":"WIDGET-RED","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":0}],"costs":[],"startedAt":"2026-10-22T21:30:00.000Z","updatedAt":"2026-10-22T21:55:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"StocktakeNotFound | ItemNotFound | LocationNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StocktakeNotFoundEncoded"},{"$ref":"#/components/schemas/ItemNotFoundEncoded"},{"$ref":"#/components/schemas/LocationNotFoundEncoded"}]}}}},"409":{"description":"StocktakeNotOpen | StocktakeLineRefused | LocationArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StocktakeNotOpenEncoded"},{"$ref":"#/components/schemas/StocktakeLineRefusedEncoded"},{"$ref":"#/components/schemas/LocationArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Save counts (`counts`: SKU, `locationId` — the default location when omitted — and the units `counted`) and costs (`costs`: SKU and `unitCostCents`, in the home currency) on an open stocktake, each replacing what it held for that pair or SKU; up to 5,000 of each per call. Nothing moves until it completes, so a tenant whose stock is mirrored from a source enters them too. Appends `inventory.stocktake-counted` with only what changed. 409 `StocktakeNotOpen` once it is completed or cancelled; 409 `StocktakeLineRefused` for a location outside its scope or a service. Idempotent by content: saving the same figures again appends nothing.\n\nRequires `stock:write` or `financials:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordStocktakeCountsEncoded"},"example":{"counts":[{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":137},{"sku":"WIDGET-RED","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":0}]}}},"required":true},"x-mcp-tool":{"name":"inventory_record_stocktake_counts","title":"Inventory: Record stocktake counts","toolset":"stocktakes","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","financials:write"],"x-example-source":{"origin":"contract"}}},"/stocktakes/{stocktakeId}/complete":{"post":{"tags":["stocktakes"],"operationId":"stocktakes.complete","parameters":[{"name":"stocktakeId","in":"path","schema":{"$ref":"#/components/schemas/StkId"},"required":true,"example":"stk_01a16585-57c0-7200-961d-25255f868ed4"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Stocktake","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeEncoded"},"examples":{"contract":{"summary":"stocktakes.complete","value":{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"completed","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counts":[{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":137},{"sku":"WIDGET-RED","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":0}],"costs":[],"startedAt":"2026-10-22T21:30:00.000Z","updatedAt":"2026-10-22T22:10:00.000Z","completedAt":"2026-10-22T22:10:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"StocktakeNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeNotFoundEncoded"}}}},"409":{"description":"StocktakeNotOpen | StocktakeIncomplete | OpeningStocktakeAtGoLive | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StocktakeNotOpenEncoded"},{"$ref":"#/components/schemas/StocktakeIncompleteEncoded"},{"$ref":"#/components/schemas/OpeningStocktakeAtGoLiveEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Complete the stocktake, appending `inventory.stocktake-completed`: every counted (SKU, location) is set to its count (a hold above it is cut). An `opening` stocktake values every stock SKU at the cost entered on it, else the SKU's cost basis — 409 `StocktakeIncomplete` names the SKUs with neither — and counts every pair nobody counted at what inventory holds, so its fact carries the whole opening balance: accounting opens the general ledger there and every ledger app may then be activated. A read-only tenant's opening stocktake is completed by going live, never by a person: 409 `OpeningStocktakeAtGoLive`. A `periodic` one's variance posts as a write-down or a gain. Idempotent by state: a stocktake completes once, so a retry on a completed stocktake is acknowledged and appends nothing.\n\nRequires `stock:write`.","x-mcp-tool":{"name":"inventory_complete_stocktake","title":"Inventory: Complete stocktake","toolset":"stocktakes","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write"],"x-example-source":{"origin":"contract"}}},"/stocktakes/{stocktakeId}/cancel":{"post":{"tags":["stocktakes"],"operationId":"stocktakes.cancel","parameters":[{"name":"stocktakeId","in":"path","schema":{"$ref":"#/components/schemas/StkId"},"required":true,"example":"stk_01a16585-57c0-7200-961d-25255f868ed4"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Stocktake","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeEncoded"},"examples":{"contract":{"summary":"stocktakes.cancel","value":{"id":"stk_01a16585-57c0-7200-961d-25255f868ed4","number":"ST-00002","kind":"periodic","status":"cancelled","locationIds":["loc_019cadd3-8330-7e12-aa44-2cd5f05da74a"],"counts":[{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":137},{"sku":"WIDGET-RED","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","counted":0}],"costs":[],"startedAt":"2026-10-22T21:30:00.000Z","updatedAt":"2026-10-22T22:05:00.000Z","cancelledAt":"2026-10-22T22:05:00.000Z","reason":"Counted the wrong aisle; starting again."}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"StocktakeNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StocktakeNotFoundEncoded"}}}},"409":{"description":"StocktakeNotOpen | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StocktakeNotOpenEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Abandon an open stocktake, appending `inventory.stocktake-cancelled`: nothing it counted moves, and if it was the opening one, the next stocktake started is the opening one. 409 `StocktakeNotOpen` once completed. Idempotent by state: a stocktake is cancelled once, so a retry on a cancelled stocktake is acknowledged and appends nothing (a second `reason` is ignored).\n\nRequires `stock:write` or `financials:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelStocktakeEncoded"},"example":{"reason":"Counted the wrong aisle; starting again."}}},"required":true},"x-mcp-tool":{"name":"inventory_cancel_stocktake","title":"Inventory: Cancel stocktake","toolset":"stocktakes","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["stock:write","financials:write"],"x-example-source":{"origin":"contract"}}},"/commission-groups":{"get":{"tags":["commissions"],"operationId":"commissions.listGroups","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionGroupList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupListEncoded"},"examples":{"contract":{"summary":"commissions.listGroups","value":{"items":[{"id":"cgr_00000000-0000-0000-0000-000000000000","name":"default","baseRateBps":200,"catalogs":{"_tag":"all"},"archived":false},{"id":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","name":"Gold","baseRateBps":500,"description":"Senior wholesale reps","catalogs":{"_tag":"all"},"archived":false}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's commission groups: each one's base rate and the catalogs its reps sell from. The `default` group (`cgr_00000000-0000-0000-0000-000000000000`) is always first, at 0 bps and every catalog until someone saves it; the rest follow by name.\n\nRequires `commissions:read`.","x-mcp-tool":{"name":"commissions_list_groups","title":"Commissions: List groups","toolset":"commissions","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:read"],"x-example-source":{"origin":"contract"}}},"/commission-groups/{groupId}":{"put":{"tags":["commissions"],"operationId":"commissions.saveGroup","parameters":[{"name":"groupId","in":"path","schema":{"$ref":"#/components/schemas/CgrId"},"required":true,"example":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionGroup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupEncoded"},"examples":{"contract":{"summary":"Open a Gold group paying 5%.","value":{"id":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","name":"Gold","baseRateBps":500,"description":"Senior wholesale reps","catalogs":{"_tag":"all"},"archived":false}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"CommissionGroupNameTaken | CommissionGroupArchived | DefaultCommissionGroupFixed | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CommissionGroupNameTakenEncoded"},{"$ref":"#/components/schemas/CommissionGroupArchivedEncoded"},{"$ref":"#/components/schemas/DefaultCommissionGroupFixedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Create or describe a commission group under the `cgr_` id the caller minted: its name (unique, case-insensitively), its base rate in basis points and a description. A new group sells from every catalog until its catalogs are set. The `default` group takes a rate and a description, never another name. Appends `inventory.commission-group-saved`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `commissions:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCommissionGroupEncoded"},"example":{"name":"Gold","baseRateBps":500,"description":"Senior wholesale reps"}}},"required":true},"x-mcp-tool":{"name":"commissions_save_group","title":"Commissions: Save group","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/commission-groups/{groupId}/catalogs":{"put":{"tags":["commissions"],"operationId":"commissions.setGroupCatalogs","parameters":[{"name":"groupId","in":"path","schema":{"$ref":"#/components/schemas/CgrId"},"required":true,"example":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionGroup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupEncoded"},"examples":{"contract":{"summary":"Gold sells from the wholesale catalog only.","value":{"id":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","name":"Gold","baseRateBps":500,"description":"Senior wholesale reps","catalogs":{"_tag":"listed","catalogIds":["cat_019e394f-ed80-7da2-823a-3ff13eb84f30"]},"archived":false}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CommissionGroupNotFound | CatalogNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CommissionGroupNotFoundEncoded"},{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}]}}}},"409":{"description":"CommissionGroupArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CommissionGroupArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set the catalogs a group's reps see and sell from: `all` (every catalog, a new one too), or `listed` with exactly the catalogs named (an empty list is none). A rep bound by their group (a sales role, neither an owner, an admin nor a holder of `commissions:read`) creates, quotes, edits and places orders only from these, and lists only these. Appends `inventory.commission-group-catalogs-set`. Idempotent by content: a retry naming the same catalogs is acknowledged and appends nothing.\n\nRequires `commissions:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetGroupCatalogsEncoded"},"example":{"catalogs":{"_tag":"listed","catalogIds":["cat_019e394f-ed80-7da2-823a-3ff13eb84f30"]}}}},"required":true},"x-mcp-tool":{"name":"commissions_set_group_catalogs","title":"Commissions: Set group catalogs","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/commission-groups/{groupId}/archive":{"post":{"tags":["commissions"],"operationId":"commissions.archiveGroup","parameters":[{"name":"groupId","in":"path","schema":{"$ref":"#/components/schemas/CgrId"},"required":true,"example":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionGroup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupEncoded"},"examples":{"contract":{"summary":"commissions.archiveGroup","value":{"id":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","name":"Gold","baseRateBps":500,"description":"Senior wholesale reps","catalogs":{"_tag":"all"},"archived":true}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CommissionGroupNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupNotFoundEncoded"}}}},"409":{"description":"CommissionGroupInUse | DefaultCommissionGroupFixed | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CommissionGroupInUseEncoded"},{"$ref":"#/components/schemas/DefaultCommissionGroupFixedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Withdraw a commission group for good: it keeps its history and takes no members, rates or catalogs. Refused for `default` and while any member is in the group (move them first). Appends `inventory.commission-group-archived`. Idempotent by state: a group archives once, and archiving an archived group is acknowledged and appends nothing.\n\nRequires `commissions:write`.","x-mcp-tool":{"name":"commissions_archive_group","title":"Commissions: Archive group","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/commission-members":{"get":{"tags":["commissions"],"operationId":"commissions.listMembers","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionMemberList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionMemberListEncoded"},"examples":{"contract":{"summary":"commissions.listMembers","value":{"items":[{"userId":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71","groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Every member put in a commission group. A member not listed is in `default` — every member is in exactly one group.\n\nRequires `commissions:read`.","x-mcp-tool":{"name":"commissions_list_members","title":"Commissions: List members","toolset":"commissions","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:read"],"x-example-source":{"origin":"contract"}}},"/commission-members/{userId}":{"put":{"tags":["commissions"],"operationId":"commissions.assignMember","parameters":[{"name":"userId","in":"path","schema":{"$ref":"#/components/schemas/UsrId"},"required":true,"example":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionMember","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionMemberEncoded"},"examples":{"contract":{"summary":"commissions.assignMember","value":{"userId":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71","groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CommissionGroupNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionGroupNotFoundEncoded"}}}},"409":{"description":"CommissionGroupArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CommissionGroupArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Put a member in a commission group (`default` included). An order already placed keeps the group its earner was in then; only orders placed after earn at the new group's rates. Appends `inventory.commission-member-assigned`. Idempotent by content: a retry naming the group the member is already in is acknowledged and appends nothing.\n\nRequires `commissions:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignCommissionGroupEncoded"},"example":{"groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40"}}},"required":true},"x-mcp-tool":{"name":"commissions_assign_member","title":"Commissions: Assign member","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/commissions/settings":{"get":{"tags":["commissions"],"operationId":"commissions.getSettings","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionSettingsEncoded"},"examples":{"contract":{"summary":"commissions.getSettings","value":{"earnedOn":"invoiced","earner":"order-rep"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's commission settings: when commission is earned (`invoiced`, `paid` or `shipped`) and who earns it (the `order-rep`, or the customer's `account-manager` at placement).\n\nRequires `commissions:read`.","x-mcp-tool":{"name":"commissions_get_settings","title":"Commissions: Get settings","toolset":"commissions","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:read"],"x-example-source":{"origin":"contract"}},"put":{"tags":["commissions"],"operationId":"commissions.saveSettings","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"CommissionSettings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionSettingsEncoded"},"examples":{"contract":{"summary":"Pay commission when the customer pays, to their account manager.","value":{"earnedOn":"paid","earner":"account-manager"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set when commission is earned and who earns it, for every group. Each order snapshots the settings when it is placed, so a change moves only orders placed after it. Appends `inventory.commission-settings-saved`. Idempotent by content: a retry that changes nothing is acknowledged and appends nothing.\n\nRequires `commissions:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionSettingsEncoded"},"example":{"earnedOn":"paid","earner":"account-manager"}}},"required":true},"x-mcp-tool":{"name":"commissions_save_settings","title":"Commissions: Save settings","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/commission":{"get":{"tags":["commissions"],"operationId":"commissions.catalogCommission","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogCommission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogCommissionEncoded"},"examples":{"contract":{"summary":"commissions.catalogCommission","value":{"catalogId":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","rules":[{"sku":"WIDGET-BLUE","rule":{"_tag":"rates","groups":[{"groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","rateBps":800}]}},{"sku":"WIDGET-PAIR","rule":{"_tag":"uncommissionable"}}],"inheritsFrom":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A catalog's commission rules, SKU-ascending: each SKU uncommissionable or rated per group, and the catalog an auto-priced catalog inherits the rules of every other SKU from.\n\nRequires `commissions:read`.","x-mcp-tool":{"name":"commissions_get_catalog_rules","title":"Commissions: Get catalog rules","toolset":"commissions","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:read"],"x-example-source":{"origin":"contract"}}},"/catalogs/{catalogId}/commission/{sku}":{"put":{"tags":["commissions"],"operationId":"commissions.setCatalogCommission","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"},{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogCommission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogCommissionEncoded"},"examples":{"contract":{"summary":"Gold earns 8% on the blue widget sold wholesale.","value":{"catalogId":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","rules":[{"sku":"WIDGET-BLUE","rule":{"_tag":"rates","groups":[{"groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","rateBps":800}]}}],"inheritsFrom":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound | CommissionGroupNotFound","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogNotFoundEncoded"},{"$ref":"#/components/schemas/CommissionGroupNotFoundEncoded"}]}}}},"409":{"description":"CatalogArchived | CommissionGroupArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/CommissionGroupArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set a catalog's commission rule for one SKU: `uncommissionable` (no group earns on it), or `rates` naming each group's rate in basis points — a group not named earns its base rate. The rule replaces whatever the SKU inherited from the catalog's base. Appends `inventory.catalog-commission-set`. Idempotent by content: a retry setting the same rule is acknowledged and appends nothing.\n\nRequires `commissions:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetCatalogCommissionEncoded"},"example":{"rule":{"_tag":"rates","groups":[{"groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","rateBps":800}]}}}},"required":true},"x-mcp-tool":{"name":"commissions_set_catalog_rule","title":"Commissions: Set catalog rule","toolset":"commissions","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}},"delete":{"tags":["commissions"],"operationId":"commissions.removeCatalogCommission","parameters":[{"name":"catalogId","in":"path","schema":{"$ref":"#/components/schemas/CatId"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"},{"name":"sku","in":"path","schema":{"$ref":"#/components/schemas/Sku"},"required":true,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"CatalogCommission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogCommissionEncoded"},"examples":{"contract":{"summary":"commissions.removeCatalogCommission","value":{"catalogId":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","rules":[],"inheritsFrom":"cat_019cadd3-8524-7934-9ee3-29b896f71f80"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"CatalogArchived | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CatalogArchivedEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Forget a catalog's commission rule for one SKU: it inherits its base catalog's again, or earns its group's base rate. Appends `inventory.catalog-commission-removed`. Idempotent by state: a SKU without a rule is acknowledged and appends nothing.\n\nRequires `commissions:write`.","x-mcp-tool":{"name":"commissions_remove_catalog_rule","title":"Commissions: Remove catalog rule","toolset":"commissions","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["commissions:write"],"x-example-source":{"origin":"contract"}}},"/commissions/terms":{"get":{"tags":["commissions"],"operationId":"commissions.terms","parameters":[{"name":"userId","in":"query","schema":{"$ref":"#/components/schemas/UsrId"},"required":false,"example":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71"},{"name":"catalogId","in":"query","schema":{"type":"string"},"required":true,"example":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30"},{"name":"sku","in":"query","schema":{"type":"string"},"required":false,"example":"WIDGET-BLUE"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"SalesTerms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesTermsEncoded"},"examples":{"contract":{"summary":"commissions.terms","value":{"settings":{"earnedOn":"invoiced","earner":"order-rep"},"rep":{"userId":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71","groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","groupName":"Gold","baseRateBps":500},"catalogs":[{"catalogId":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","open":true,"rules":[{"sku":"WIDGET-BLUE","commission":{"catalogId":"cat_019e394f-ed80-7da2-823a-3ff13eb84f30","rule":{"_tag":"rates","groups":[{"groupId":"cgr_019e5a10-4c2a-7d11-9a3e-5b7c2d8e1f40","rateBps":800}]}}}]}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"CatalogNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The terms an order is snapshotted under: the settings, the earner's group (when `userId` names one) and, per catalog, whether that group sells from it and each SKU's rule up the catalog's chain of bases. Fulfillment asks this as it creates, places and re-attributes an order.\n\nRequires `commissions:read`.","x-mcp-withheld":"Fulfillment asks it under its own credential as it snapshots an order; an agent reads the rates on the order and the rules with `commission_get_catalog_rules`.","x-required-scopes":["commissions:read"],"x-example-source":{"origin":"contract"}}},"/events":{"get":{"tags":["events"],"operationId":"events.list","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"required":false,"example":"1042"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"500"},{"name":"upTo","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/inventory.item-createdEncoded"},{"$ref":"#/components/schemas/inventory.item-updatedEncoded"},{"$ref":"#/components/schemas/inventory.stock-adjustedEncoded"},{"$ref":"#/components/schemas/inventory.stock-receivedEncoded"},{"$ref":"#/components/schemas/inventory.stock-identifiedEncoded"},{"$ref":"#/components/schemas/inventory.shortfall-recordedEncoded"},{"$ref":"#/components/schemas/inventory.stock-dispatchedEncoded"},{"$ref":"#/components/schemas/inventory.stock-damagedEncoded"},{"$ref":"#/components/schemas/inventory.stock-disposedEncoded"},{"$ref":"#/components/schemas/inventory.stock-reservedEncoded"},{"$ref":"#/components/schemas/inventory.stock-releasedEncoded"},{"$ref":"#/components/schemas/inventory.stock-returnedEncoded"},{"$ref":"#/components/schemas/inventory.incoming-expectedEncoded"},{"$ref":"#/components/schemas/inventory.incoming-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.location-createdEncoded"},{"$ref":"#/components/schemas/inventory.location-updatedEncoded"},{"$ref":"#/components/schemas/inventory.location-archivedEncoded"},{"$ref":"#/components/schemas/inventory.location-boundEncoded"},{"$ref":"#/components/schemas/inventory.location-unboundEncoded"},{"$ref":"#/components/schemas/inventory.channel-connectedEncoded"},{"$ref":"#/components/schemas/inventory.channel-updatedEncoded"},{"$ref":"#/components/schemas/inventory.channel-intake-reportedEncoded"},{"$ref":"#/components/schemas/inventory.channel-attention-reportedEncoded"},{"$ref":"#/components/schemas/inventory.channel-disconnectedEncoded"},{"$ref":"#/components/schemas/inventory.source-connectedEncoded"},{"$ref":"#/components/schemas/inventory.source-updatedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-createdEncoded"},{"$ref":"#/components/schemas/inventory.transfer-despatchedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-receivedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-completedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-startedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-countedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-completedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.settings-configuredEncoded"},{"$ref":"#/components/schemas/inventory.home-currency-lockedEncoded"},{"$ref":"#/components/schemas/inventory.tax-settings-configuredEncoded"},{"$ref":"#/components/schemas/inventory.accounting-basis-setEncoded"},{"$ref":"#/components/schemas/inventory.view-savedEncoded"},{"$ref":"#/components/schemas/inventory.view-deletedEncoded"},{"$ref":"#/components/schemas/inventory.account-savedEncoded"},{"$ref":"#/components/schemas/inventory.account-deletedEncoded"},{"$ref":"#/components/schemas/inventory.chart-sync-requestedEncoded"},{"$ref":"#/components/schemas/inventory.product-createdEncoded"},{"$ref":"#/components/schemas/inventory.product-updatedEncoded"},{"$ref":"#/components/schemas/inventory.product-archivedEncoded"},{"$ref":"#/components/schemas/inventory.variant-addedEncoded"},{"$ref":"#/components/schemas/inventory.variant-updatedEncoded"},{"$ref":"#/components/schemas/inventory.variant-removedEncoded"},{"$ref":"#/components/schemas/inventory.product-options-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-createdEncoded"},{"$ref":"#/components/schemas/inventory.catalog-updatedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-archivedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-product-includedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-product-excludedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-price-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-price-removedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-locations-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-pricing-configuredEncoded"},{"$ref":"#/components/schemas/inventory.fx-rate-recordedEncoded"},{"$ref":"#/components/schemas/inventory.sku-cost-setEncoded"},{"$ref":"#/components/schemas/inventory.asset-uploadedEncoded"},{"$ref":"#/components/schemas/inventory.asset-removedEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-savedEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-catalogs-setEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-archivedEncoded"},{"$ref":"#/components/schemas/inventory.commission-member-assignedEncoded"},{"$ref":"#/components/schemas/inventory.commission-settings-savedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-commission-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-commission-removedEncoded"}]}},"examples":{"contract":{"summary":"events.list","value":[{"_tag":"inventory.stock-dispatched","eventId":"evt_01a1615a-c0e0-7d38-a94d-ee5249f39be3","txId":"tx_01a1615a-c0e0-7de2-b618-5b6075c9f4c7","tenantId":"org_019cadd3-7f48-7813-b601-1d0e5ec31353","sequence":1042,"occurredAt":"2026-10-22T02:05:00.000Z","source":"inventory-manager","version":1,"actor":{"_tag":"user","id":"usr_019cadd3-7fc0-792b-bb42-1992ef490f3b"},"correlationId":"req_01a1615a-c0e0-756f-be6c-4dc5e8f50d4d","payload":{"sku":"WIDGET-BLUE","locationId":"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a","quantity":2,"orderId":"ord_01a1612f-7ea8-705d-b799-e8d57826848d","reference":"dsp_309cca80-6f93-1b13-35a3-a6c100d3dd4d"}}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replay committed events at-or-after `since` (a journal sequence number), oldest first. Use to catch up before subscribing to `/events/stream`. One response is a page: `limit` defaults to 500 and is capped at 5000 (an over-cap request is clamped). Pages are `sequence`-ordered and the boundary is stable — repeat with `since=<last event's sequence + 1>` until a page comes back smaller than `limit` to replay the journal exactly once. `upTo` (inclusive) ends the replay at a sequence instead of the journal's head — with `GET /events/head` it replays the journal as it stood at a moment. Appends nothing: a read of facts already journalled.\n\nRequires `stock:read` or `products:read` or `catalogs:read` or `locations:read`.","x-mcp-withheld":"The journal replay a consumer pages through to build its projection; agents read the projections the list and get tools serve, and the audit trail (`audit_trail`) for history.","x-required-scopes":["stock:read","products:read","catalogs:read","locations:read"],"x-example-source":{"origin":"contract"}}},"/events/head":{"get":{"tags":["events"],"operationId":"events.head","parameters":[{"name":"at","in":"query","schema":{"type":"string"},"required":true,"example":"2026-10-22T03:00:00.000Z"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Where a tenant's journal stood at a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalHead"},"examples":{"contract":{"summary":"events.head","value":{"at":"2026-10-22T03:00:00.000Z","sequence":1042}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The journal's position at a moment: the last `sequence` the database had recorded for this tenant at `at` (absent when it held nothing yet), by the database's own clock rather than the service's. Replaying with `upTo=<sequence>` then gives the journal exactly as it stood then; a set of heads taken at one `at` is a consistent cut across journals. Appends nothing: a read of facts already journalled.\n\nRequires `stock:read` or `products:read` or `catalogs:read` or `locations:read`.","x-mcp-withheld":"Where a journal stood at a moment, for a consumer cutting journals to replay them as of then; agents read history through the audit trail (`audit_trail`).","x-required-scopes":["stock:read","products:read","catalogs:read","locations:read"],"x-example-source":{"origin":"contract"}}},"/events/stream":{"get":{"tags":["events"],"operationId":"events.stream","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"string"},"examples":{"contract":{"summary":"Each frame is one inventory fact, JSON-encoded, sent as it commits.","value":"data: {\"_tag\":\"inventory.stock-dispatched\",\"eventId\":\"evt_01a1615a-c0e0-7d38-a94d-ee5249f39be3\",\"txId\":\"tx_01a1615a-c0e0-7de2-b618-5b6075c9f4c7\",\"tenantId\":\"org_019cadd3-7f48-7813-b601-1d0e5ec31353\",\"sequence\":1042,\"occurredAt\":\"2026-10-22T02:05:00.000Z\",\"source\":\"inventory-manager\",\"version\":1,\"actor\":{\"_tag\":\"user\",\"id\":\"usr_019cadd3-7fc0-792b-bb42-1992ef490f3b\"},\"correlationId\":\"req_01a1615a-c0e0-756f-be6c-4dc5e8f50d4d\",\"payload\":{\"sku\":\"WIDGET-BLUE\",\"locationId\":\"loc_019cadd3-8330-7e12-aa44-2cd5f05da74a\",\"quantity\":2,\"orderId\":\"ord_01a1612f-7ea8-705d-b799-e8d57826848d\",\"reference\":\"dsp_309cca80-6f93-1b13-35a3-a6c100d3dd4d\"}}\n\n"}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Real-time push over Server-Sent Events (`text/event-stream`). Each `data:` frame is one JSON-encoded `InventoryEvent`; OpenAPI cannot model event streams, so the success schema is a placeholder string. Delivery is best-effort from a bounded buffer: a consumer that falls far enough behind loses its *oldest* frames rather than growing the server without limit. Recover any gap — dropped frames or a broken connection alike — by reconnecting and replaying `GET /events?since=<lastSeen + 1>`.\n\nRequires `stock:read` or `products:read` or `catalogs:read` or `locations:read`.","x-mcp-withheld":"A server-sent event stream for live consumers, not a request an agent can hold open through a tool call.","x-required-scopes":["stock:read","products:read","catalogs:read","locations:read"],"x-example-source":{"origin":"contract"}}}},"components":{"schemas":{"BooleanString":{"type":"string","enum":["true","false"],"description":"A boolean as a query string spells it: `true` or `false`."},"ItemSortKey":{"type":"string","enum":["sku","name","tracking","kind","createdAt","updatedAt"],"description":"The column the SKU grid is ordered by (master-data columns only)"},"SortOrder":{"type":"string","enum":["asc","desc"],"description":"The direction a list is ordered in: `asc` (ascending) or `desc` (descending)"},"ItmId":{"type":"string","pattern":"^itm_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A itm-prefixed uuid, e.g. itm_9f8c1c2e-0000-4000-8000-000000000000"},"Sku":{"type":"string","minLength":1,"pattern":"^\\s*[A-Z0-9](?:[A-Z0-9 ._/-]*[A-Z0-9._/-])?\\s*$","description":"A-Z 0-9 space - _ . / (trimmed, uppercased)"},"Tracking":{"type":"string","enum":["none","serial","batch"],"description":"How a SKU's units are identified: `none` — bare quantities; `serial` — one serial number per unit; `batch` — one batch (lot) number per lot"},"CostingMethod":{"type":"string","enum":["fifo","fefo","special-batch","special-serial"],"description":"How cost layers are consumed: `fifo` — first in, first out; `fefo` — first expiring, first out; `special-batch` / `special-serial` — the cost of the very lot or unit picked"},"ItemKind":{"type":"string","enum":["stock","service","gift-card"],"description":"`stock` — a physical good held at a location; `service`, `gift-card` — sold, never held"},"BarcodeValue":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+$","description":"the code as scanned; no whitespace"},"BarcodeType":{"type":"string","enum":["gtin","ean","upc","isbn","asin","ns-pid"],"description":"The standard a barcode conforms to, its length and check digit checked; `ns-pid` is a manufacturer's part number"},"BarcodeEncoded":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BarcodeValue"},"type":{"$ref":"#/components/schemas/BarcodeType"}},"required":["value"],"additionalProperties":false},"Barcodes":{"type":"array","items":{"$ref":"#/components/schemas/BarcodeEncoded"},"maxItems":20},"CountryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, upper case"},"HsCode":{"type":"string","pattern":"^[0-9][0-9. ]*$","description":"6 to 13 digits; dots and spaces are dropped"},"CountryHsCodeEncoded":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode"},"code":{"$ref":"#/components/schemas/HsCode"}},"required":["code"],"additionalProperties":false},"HsCodes":{"type":"array","items":{"$ref":"#/components/schemas/CountryHsCodeEncoded"},"maxItems":50},"AccountCodeEncoded":{"anyOf":[{"type":"string"},{"type":"integer"}]},"AccountMappingEncoded":{"type":"object","properties":{"inventory":{"$ref":"#/components/schemas/AccountCodeEncoded"},"revenue":{"$ref":"#/components/schemas/AccountCodeEncoded"},"expense":{"$ref":"#/components/schemas/AccountCodeEncoded"}},"required":["inventory","revenue","expense"],"additionalProperties":false},"TaxClass":{"type":"string","enum":["standard","reduced","zero-rated","exempt","out-of-scope"],"description":"What a SKU is, for tax: `standard` (the standard rate), `reduced` (a reduced rate, e.g. UK 5 %), `zero-rated` (taxable at nothing — AU GST-free, UK/NZ zero-rated), `exempt` (input-taxed / exempt) or `out-of-scope` (not a supply: gift cards, deposits, duties)"},"LocId":{"type":"string","pattern":"^loc_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A loc-prefixed uuid, e.g. loc_9f8c1c2e-0000-4000-8000-000000000000"},"LocationStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"onHand":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"damaged":{"type":"integer","minimum":0},"awaitingIdentification":{"type":"integer","minimum":0},"inTransit":{"type":"integer","minimum":0},"incoming":{"type":"integer","minimum":0}},"required":["locationId","onHand","reserved","damaged","awaitingIdentification","inTransit","incoming"],"additionalProperties":false},"SkuCostSource":{"type":"string","enum":["receipt","set","stocktake","kit"],"description":"`receipt` — the latest receive's unit cost; `set` — set by hand or by an import; `stocktake` — the cost a completed stocktake valued it at; `kit` — summed from the components"},"ItemCost":{"type":"object","properties":{"costCents":{"type":"number","minimum":0},"source":{"$ref":"#/components/schemas/SkuCostSource"},"at":{"type":"string"}},"required":["costCents","source","at"],"additionalProperties":false},"InventoryItemEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ItmId"},"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string","minLength":1,"maxLength":200},"tracking":{"$ref":"#/components/schemas/Tracking"},"costingMethod":{"$ref":"#/components/schemas/CostingMethod"},"kind":{"$ref":"#/components/schemas/ItemKind"},"counted":{"type":"boolean"},"sellable":{"type":"boolean"},"barcodes":{"$ref":"#/components/schemas/Barcodes"},"hsCodes":{"$ref":"#/components/schemas/HsCodes"},"countryOfOrigin":{"$ref":"#/components/schemas/CountryCode"},"weightGrams":{"type":"integer","exclusiveMinimum":0},"packedSize":{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},"ownPackaging":{"type":"boolean"},"orderRules":{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},"accounts":{"$ref":"#/components/schemas/AccountMappingEncoded"},"taxClass":{"$ref":"#/components/schemas/TaxClass"},"stock":{"type":"array","items":{"$ref":"#/components/schemas/LocationStockEncoded"}},"backordered":{"type":"integer","minimum":0},"cost":{"$ref":"#/components/schemas/ItemCost"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sku","name","createdAt","updatedAt"],"additionalProperties":false},"LocationLevelsEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"fulfillable":{"type":"boolean"},"onHand":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0},"damaged":{"type":"integer","minimum":0},"awaitingIdentification":{"type":"integer","minimum":0},"inTransit":{"type":"integer","minimum":0},"incoming":{"type":"integer","minimum":0}},"required":["locationId","fulfillable","onHand","reserved","available","damaged","awaitingIdentification","inTransit","incoming"],"additionalProperties":false},"StockLevelsEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"onHand":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0},"damaged":{"type":"integer","minimum":0},"awaitingIdentification":{"type":"integer","minimum":0},"inTransit":{"type":"integer","minimum":0},"incoming":{"type":"integer","minimum":0},"backordered":{"type":"integer","minimum":0},"projected":{"type":"integer"},"byLocation":{"type":"array","items":{"$ref":"#/components/schemas/LocationLevelsEncoded"}},"asOf":{"type":"string"}},"required":["sku","onHand","reserved","available","damaged","awaitingIdentification","inTransit","incoming","backordered","projected","byLocation","asOf"],"additionalProperties":false},"InventoryItemSummaryEncoded":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItemEncoded"},"levels":{"$ref":"#/components/schemas/StockLevelsEncoded"}},"required":["item","levels"],"additionalProperties":false},"PrdId":{"type":"string","pattern":"^prd_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A prd-prefixed uuid, e.g. prd_9f8c1c2e-0000-4000-8000-000000000000"},"VarId":{"type":"string","pattern":"^var_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A var-prefixed uuid, e.g. var_9f8c1c2e-0000-4000-8000-000000000000"},"VariantKindTag":{"type":"string","enum":["stocked","composite"],"description":"A variant's kind by name: `stocked` — its own SKU's stock; `composite` — a kit made of components"},"Sku_1":{"type":"string","minLength":1,"pattern":"^\\s*[A-Z0-9](?:[A-Z0-9 ._/-]*[A-Z0-9._/-])?\\s*$","description":"A-Z 0-9 space - _ . / (trimmed, uppercased)"},"VariantAvailabilityEncoded":{"type":"object","properties":{"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"kind":{"$ref":"#/components/schemas/VariantKindTag"},"onHand":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0},"projected":{"type":"integer"},"components":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku_1"},"quantity":{"type":"integer","exclusiveMinimum":0},"available":{"type":"integer","minimum":0},"kits":{"type":"integer","minimum":0}},"required":["sku","quantity","available","kits"],"additionalProperties":false}},"limitedBy":{"type":"array","items":{"$ref":"#/components/schemas/Sku_1"}}},"required":["variantId","sku","kind","onHand","available","projected"],"additionalProperties":false},"CompositeItemSummaryEncoded":{"type":"object","properties":{"composite":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string"},"productId":{"$ref":"#/components/schemas/PrdId"},"productTitle":{"type":"string"},"variantId":{"$ref":"#/components/schemas/VarId"},"components":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false}}},"required":["sku","name","productId","productTitle","variantId","components"],"additionalProperties":false},"availability":{"$ref":"#/components/schemas/VariantAvailabilityEncoded"}},"required":["composite","availability"],"additionalProperties":false},"InventoryGridPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/InventoryItemSummaryEncoded"},{"$ref":"#/components/schemas/CompositeItemSummaryEncoded"}]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"CatalogNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CatalogNotFound"]},"catalogId":{"type":"string"}},"required":["_tag","catalogId"],"additionalProperties":false},"UnauthorizedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"TokenAlreadyUsedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TokenAlreadyUsed"]},"tokenId":{"type":"string"}},"required":["_tag","tokenId"],"additionalProperties":false},"RequestLogUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["RequestLogUnavailable"]},"tokenId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","tokenId","reason"],"additionalProperties":false},"TenantRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TenantRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"ScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ScopeRequired"]},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","required"],"additionalProperties":false},"PlatformAdminRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PlatformAdminRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"SubscriptionRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SubscriptionRequired"]},"status":{"type":"string"}},"required":["_tag","status"],"additionalProperties":false},"MirroredFromSourceEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MirroredFromSource"]},"source":{"type":"string"}},"required":["_tag","source"],"additionalProperties":false},"ItemNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ItemNotFound"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"LocationNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationNotFound"]},"locationId":{"type":"string"}},"required":["_tag","locationId"],"additionalProperties":false},"LocationArchivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationArchived"]},"locationId":{"type":"string"}},"required":["_tag","locationId"],"additionalProperties":false},"BarcodeValue_1":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+$","description":"the barcode exactly as scanned"},"BarcodeMatchEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"barcode":{"$ref":"#/components/schemas/BarcodeEncoded"}},"required":["sku","barcode"],"additionalProperties":false},"BarcodeNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["BarcodeNotFound"]},"barcode":{"type":"string"}},"required":["_tag","barcode"],"additionalProperties":false},"CreateInventoryItemEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":0},"locationId":{"$ref":"#/components/schemas/LocId"},"tracking":{"$ref":"#/components/schemas/Tracking"},"costingMethod":{"$ref":"#/components/schemas/CostingMethod"},"kind":{"$ref":"#/components/schemas/ItemKind"},"counted":{"type":"boolean"},"sellable":{"type":"boolean"},"barcodes":{"$ref":"#/components/schemas/Barcodes"},"hsCodes":{"$ref":"#/components/schemas/HsCodes"},"countryOfOrigin":{"$ref":"#/components/schemas/CountryCode"},"weightGrams":{"type":"integer","exclusiveMinimum":0},"packedSize":{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},"ownPackaging":{"type":"boolean"},"orderRules":{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},"accounts":{"$ref":"#/components/schemas/AccountMappingEncoded"},"taxClass":{"$ref":"#/components/schemas/TaxClass"}},"required":["sku","name","quantity"],"additionalProperties":false},"SkuConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuConflict"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"SkuAlphabet":{"type":"string","enum":["strict","extended"],"description":"Which characters a tenant's new SKUs may use — `strict` (letters, digits, - and _; the default) or `extended` (also spaces, . and /)"},"SkuNotAllowedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuNotAllowed"]},"sku":{"type":"string"},"alphabet":{"$ref":"#/components/schemas/SkuAlphabet"},"allowed":{"type":"string"}},"required":["_tag","sku","alphabet","allowed"],"additionalProperties":false},"BarcodeConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["BarcodeConflict"]},"barcode":{"type":"string"},"sku":{"type":"string"}},"required":["_tag","barcode","sku"],"additionalProperties":false},"AccountRole":{"type":"string","enum":["inventory","revenue","expense"],"description":"A slot of a SKU's account mapping: `inventory` — the asset account its stock is valued in; `revenue` — the income account a sale credits; `expense` — the cost-of-sales account a consumption debits"},"UnknownAccountCodeEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["UnknownAccountCode"]},"role":{"$ref":"#/components/schemas/AccountRole"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"}},"required":["_tag","role","code"],"additionalProperties":false},"BarcodeType_1":{"type":"string","enum":["gtin","ean","upc","isbn","asin","ns-pid"],"description":"The standard a barcode conforms to, its length and check digit checked; `ns-pid` is a manufacturer's part number"},"CountryCode_1":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, upper case"},"HsCode_1":{"type":"string","pattern":"^[0-9][0-9. ]*$","description":"6 to 13 digits; dots and spaces are dropped"},"UpdateInventoryItemEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"barcodes":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BarcodeValue"},"type":{"$ref":"#/components/schemas/BarcodeType_1"}},"required":["value"],"additionalProperties":false},"maxItems":20},"hsCodes":{"type":"array","items":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode_1"},"code":{"$ref":"#/components/schemas/HsCode_1"}},"required":["code"],"additionalProperties":false},"maxItems":50},"countryOfOrigin":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"packedSize":{"anyOf":[{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},{"type":"null"}]},"ownPackaging":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"orderRules":{"anyOf":[{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},{"type":"null"}]},"kind":{"$ref":"#/components/schemas/ItemKind"},"counted":{"type":"boolean"},"sellable":{"type":"boolean"},"tracking":{"$ref":"#/components/schemas/Tracking"},"costingMethod":{"$ref":"#/components/schemas/CostingMethod"},"accounts":{"type":"object","properties":{"inventory":{"anyOf":[{"type":"string"},{"type":"integer"}]},"revenue":{"anyOf":[{"type":"string"},{"type":"integer"}]},"expense":{"anyOf":[{"type":"string"},{"type":"integer"}]}},"required":["inventory","revenue","expense"],"additionalProperties":false},"taxClass":{"anyOf":[{"$ref":"#/components/schemas/TaxClass"},{"type":"null"}]}},"additionalProperties":false},"ItemUpdateRefusedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ItemUpdateRefused"]},"sku":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","sku","reason"],"additionalProperties":false},"SkuCostEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"costCents":{"type":"number","minimum":0},"source":{"$ref":"#/components/schemas/SkuCostSource"},"at":{"type":"string"}},"required":["sku","costCents","source","at"],"additionalProperties":false},"SkuCostNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuCostNotFound"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"SetSkuCostEncoded":{"type":"object","properties":{"costCents":{"type":"number","minimum":0}},"required":["costCents"],"additionalProperties":false},"SkuCostNotSettableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuCostNotSettable"]},"sku":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","sku","reason"],"additionalProperties":false},"EvtId":{"type":"string","pattern":"^evt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A evt-prefixed uuid, e.g. evt_9f8c1c2e-0000-4000-8000-000000000000"},"TxId":{"type":"string","pattern":"^tx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A tx-prefixed uuid, e.g. tx_9f8c1c2e-0000-4000-8000-000000000000"},"TenantId":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"An org-prefixed uuid, e.g. org_9f8c1c2e-0000-4000-8000-000000000000; a sandbox tenant is org_test_<uuid>"},"UsrId":{"type":"string","pattern":"^usr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A usr-prefixed uuid, e.g. usr_9f8c1c2e-0000-4000-8000-000000000000"},"AppId":{"type":"string","pattern":"^app_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A app-prefixed uuid, e.g. app_9f8c1c2e-0000-4000-8000-000000000000"},"InsId":{"type":"string","pattern":"^ins_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ins-prefixed uuid, e.g. ins_9f8c1c2e-0000-4000-8000-000000000000"},"CplId":{"type":"string","pattern":"^cpl_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cpl-prefixed uuid, e.g. cpl_9f8c1c2e-0000-4000-8000-000000000000"},"Actor":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/UsrId"},"impersonatedBy":{"type":"string","minLength":1},"viaPartner":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["app"]},"id":{"$ref":"#/components/schemas/AppId"},"installationId":{"$ref":"#/components/schemas/InsId"}},"required":["_tag","id","installationId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["customer"]},"id":{"$ref":"#/components/schemas/CplId"}},"required":["_tag","id"],"additionalProperties":false}]},"inventory.item-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.item-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ItmId"},"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":0},"locationId":{"$ref":"#/components/schemas/LocId"},"tracking":{"$ref":"#/components/schemas/Tracking"},"costingMethod":{"$ref":"#/components/schemas/CostingMethod"},"kind":{"$ref":"#/components/schemas/ItemKind"},"counted":{"type":"boolean"},"sellable":{"type":"boolean"},"barcodes":{"$ref":"#/components/schemas/Barcodes"},"hsCodes":{"$ref":"#/components/schemas/HsCodes"},"countryOfOrigin":{"$ref":"#/components/schemas/CountryCode"},"weightGrams":{"type":"integer","exclusiveMinimum":0},"packedSize":{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},"ownPackaging":{"type":"boolean"},"orderRules":{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},"accounts":{"$ref":"#/components/schemas/AccountMappingEncoded"},"taxClass":{"$ref":"#/components/schemas/TaxClass"}},"required":["id","sku","name","quantity","locationId","tracking","costingMethod"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.item-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.item-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string","minLength":1,"maxLength":200},"barcodes":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BarcodeValue"},"type":{"$ref":"#/components/schemas/BarcodeType_1"}},"required":["value"],"additionalProperties":false},"maxItems":20},"hsCodes":{"type":"array","items":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode_1"},"code":{"$ref":"#/components/schemas/HsCode_1"}},"required":["code"],"additionalProperties":false},"maxItems":50},"countryOfOrigin":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"packedSize":{"anyOf":[{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},{"type":"null"}]},"ownPackaging":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"orderRules":{"anyOf":[{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},{"type":"null"}]},"kind":{"$ref":"#/components/schemas/ItemKind"},"counted":{"type":"boolean"},"sellable":{"type":"boolean"},"tracking":{"$ref":"#/components/schemas/Tracking"},"costingMethod":{"$ref":"#/components/schemas/CostingMethod"},"accounts":{"type":"object","properties":{"inventory":{"anyOf":[{"type":"string"},{"type":"integer"}]},"revenue":{"anyOf":[{"type":"string"},{"type":"integer"}]},"expense":{"anyOf":[{"type":"string"},{"type":"integer"}]}},"required":["inventory","revenue","expense"],"additionalProperties":false},"taxClass":{"anyOf":[{"$ref":"#/components/schemas/TaxClass"},{"type":"null"}]}},"required":["sku"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"AdjustReason":{"type":"string","enum":["received","sold","damaged","recount","returned"],"description":"Why a quantity was corrected by hand: `received` (outside a purchase order), `sold` (outside an order), `damaged`, `recount` (a stocktake count) or `returned`"},"inventory.stock-adjustedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-adjusted"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"delta":{"type":"integer"},"reason":{"$ref":"#/components/schemas/AdjustReason"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","delta","reason","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"PoId":{"type":"string","pattern":"^po_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A po-prefixed uuid, e.g. po_9f8c1c2e-0000-4000-8000-000000000000"},"Currency":{"type":"string"},"IsoDay":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A calendar day, e.g. 2026-03-31"},"FxCaptureSource":{"type":"string","enum":["rba","rbnz","ecb","boe","fed","boc","norges-bank","nationalbanken","actual","same"],"description":"Where a captured rate came from: a central bank (`rba`, `rbnz`, `ecb`, `boe`, `fed`, `boc`, `norges-bank`, `nationalbanken`), `actual` (the counterparty's own figure for what the money became) or `same` (the document is in the home currency, rate 1)"},"Currency_1":{"type":"string"},"FxCapture":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"home":{"$ref":"#/components/schemas/Currency"},"rate":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"rateDate":{"$ref":"#/components/schemas/IsoDay"},"source":{"$ref":"#/components/schemas/FxCaptureSource"},"via":{"$ref":"#/components/schemas/Currency_1"}},"required":["currency","home","rate","rateDate","source"],"additionalProperties":false,"description":"The rate a money fact was booked at, captured when it committed: `rate` units of `home` per one unit of the document's `currency`, from `source` for `rateDate` (`via` a cross); `same` is a document in the home currency, rate 1"},"inventory.stock-receivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-received"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"poId":{"$ref":"#/components/schemas/PoId"},"unitCostCents":{"type":"number","minimum":0},"costCurrency":{"type":"string"},"fx":{"$ref":"#/components/schemas/FxCapture"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"SerialNumber":{"type":"string","minLength":1,"maxLength":64},"BatchNumber":{"type":"string","minLength":1,"maxLength":64},"inventory.stock-identifiedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-identified"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"serials":{"type":"array","items":{"$ref":"#/components/schemas/SerialNumber"}},"batchNumber":{"$ref":"#/components/schemas/BatchNumber"},"expiresAt":{"type":"string"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"OrdId":{"type":"string","pattern":"^ord_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ord-prefixed uuid, e.g. ord_9f8c1c2e-0000-4000-8000-000000000000"},"inventory.shortfall-recordedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.shortfall-recorded"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"orderId":{"$ref":"#/components/schemas/OrdId"},"quantity":{"type":"integer","minimum":0}},"required":["sku","orderId","quantity"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stock-dispatchedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-dispatched"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stock-damagedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-damaged"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"DisposeBucket":{"type":"string","enum":["onHand","damaged"],"description":"Which bucket a disposal empties: `onHand` — sellable stock; `damaged` — the damaged bucket"},"inventory.stock-disposedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-disposed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"bucket":{"$ref":"#/components/schemas/DisposeBucket"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","bucket","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stock-reservedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-reserved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","orderId","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stock-releasedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-released"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","quantity","orderId","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ReturnCondition":{"type":"string","enum":["sellable","damaged"],"description":"Where returned units land: `sellable` — back on sale; `damaged` — the damaged bucket"},"inventory.stock-returnedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stock-returned"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1},"condition":{"$ref":"#/components/schemas/ReturnCondition"}},"required":["sku","locationId","quantity","reference","condition"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.incoming-expectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.incoming-expected"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"poId":{"$ref":"#/components/schemas/PoId"},"quantity":{"type":"integer","exclusiveMinimum":0},"reference":{"type":"string","minLength":1}},"required":["sku","locationId","poId","quantity","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.incoming-cancelledEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.incoming-cancelled"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"poId":{"$ref":"#/components/schemas/PoId"},"reference":{"type":"string","minLength":1}},"required":["sku","poId","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"PadId":{"type":"string","pattern":"^pad_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A platform address: a pad-prefixed uuid"},"PostalAddress":{"type":"object","properties":{"firstName":{"type":"string","maxLength":500},"lastName":{"type":"string","maxLength":500},"company":{"type":"string","maxLength":500},"address1":{"type":"string","maxLength":500},"address2":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":500},"province":{"type":"string","maxLength":500},"provinceCode":{"type":"string","maxLength":10},"country":{"type":"string","maxLength":500},"countryCode":{"type":"string","allOf":[{"minLength":2},{"maxLength":2}]},"zip":{"type":"string","maxLength":20},"phone":{"type":"string","maxLength":40},"verifiedAddressId":{"$ref":"#/components/schemas/PadId"}},"additionalProperties":false},"GeoPoint":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["latitude","longitude"],"additionalProperties":false,"description":"A point on the earth in decimal degrees (WGS 84): where a geocoder placed an address."},"LocationRank":{"type":"integer","minimum":0,"maximum":9999,"description":"where a site sits in the routing preference order, lowest first"},"inventory.location-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.location-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"name":{"type":"string","minLength":1,"maxLength":120},"fulfillable":{"type":"boolean"},"note":{"type":"string"},"address":{"$ref":"#/components/schemas/PostalAddress"},"coordinates":{"$ref":"#/components/schemas/GeoPoint"},"rank":{"$ref":"#/components/schemas/LocationRank"},"isDefault":{"type":"boolean"}},"required":["locationId","name","fulfillable"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"GeoPoint_1":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["latitude","longitude"],"additionalProperties":false,"description":"A point on the earth in decimal degrees (WGS 84): where a geocoder placed an address."},"inventory.location-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.location-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"name":{"type":"string"},"fulfillable":{"type":"boolean"},"note":{"type":"string"},"address":{"$ref":"#/components/schemas/PostalAddress"},"coordinates":{"$ref":"#/components/schemas/GeoPoint_1"},"rank":{"$ref":"#/components/schemas/LocationRank"}},"required":["locationId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.location-archivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.location-archived"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"}},"required":["locationId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ChnId":{"type":"string","pattern":"^chn_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A chn-prefixed uuid, e.g. chn_9f8c1c2e-0000-4000-8000-000000000000"},"inventory.location-boundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.location-bound"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"channelId":{"$ref":"#/components/schemas/ChnId"},"externalId":{"type":"string","minLength":1},"externalName":{"type":"string"}},"required":["locationId","channelId","externalId","externalName"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.location-unboundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.location-unbound"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"channelId":{"$ref":"#/components/schemas/ChnId"}},"required":["locationId","channelId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ChannelType":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,31}$","description":"The kind of channel, a slug its app declares."},"CatId":{"type":"string","pattern":"^cat_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cat-prefixed uuid, e.g. cat_9f8c1c2e-0000-4000-8000-000000000000"},"ChannelPublicationEncoded":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"externalId":{"type":"string","minLength":1,"maxLength":255},"externalName":{"type":"string","maxLength":255}},"required":["catalogId","externalId","externalName"],"additionalProperties":false},"CurrencyCode":{"type":"string"},"ChannelCollectionKind":{"type":"string","enum":["capture-authorised","charge-saved-method"],"description":"`capture-authorised` — take money the buyer's card authorised at the channel's checkout (in full or in part); `charge-saved-method` — charge a payment method the buyer saved with the channel for later payments (net terms, deposits, balances)"},"ChannelCapabilityState":{"type":"string","enum":["available","pending"],"description":"`available` — usable now; `pending` — the channel supports it but cannot use it for this account yet (a permission still awaiting approval): shown, explained by its `note`, and refused if asked for"},"inventory.channel-connectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.channel-connected"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"},"appId":{"$ref":"#/components/schemas/AppId"},"type":{"$ref":"#/components/schemas/ChannelType"},"externalId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/ChannelPublicationEncoded"}},"orderUrl":{"type":"string"},"settingsPath":{"type":"string"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"collects":{"type":"array","items":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ChannelCollectionKind"},"state":{"$ref":"#/components/schemas/ChannelCapabilityState"},"processor":{"type":"string","minLength":1,"maxLength":200},"note":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","state","processor"],"additionalProperties":false}}},"required":["channelId","type","externalId","name","catalogs"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.channel-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.channel-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"},"name":{"type":"string","minLength":1},"catalogs":{"type":"array","items":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"externalId":{"type":"string","minLength":1,"maxLength":255},"externalName":{"type":"string","maxLength":255}},"required":["catalogId","externalId","externalName"],"additionalProperties":false}},"orderUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"settingsPath":{"anyOf":[{"type":"string"},{"type":"null"}]},"currency":{"anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]},"collects":{"type":"array","items":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ChannelCollectionKind"},"state":{"$ref":"#/components/schemas/ChannelCapabilityState"},"processor":{"type":"string","minLength":1,"maxLength":200},"note":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","state","processor"],"additionalProperties":false}}},"required":["channelId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.channel-intake-reportedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.channel-intake-reported"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"},"importing":{"type":"boolean"},"notBroughtIn":{"type":"integer","minimum":0}},"required":["channelId","importing","notBroughtIn"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"AttentionSeverity":{"type":"string","enum":["critical","warning"],"description":"How loudly something asks for attention: `critical` (out of step now) or `warning` (a person should look)."},"ChannelSettingsPath":{"type":"string","maxLength":200,"pattern":"^(\\/[A-Za-z0-9_-]+)+$","description":"A path in the admin where the channel is configured, e.g. `/settings/channels/<type>/conn_…`."},"ChannelAttentionItemEncoded":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,47}$"},"severity":{"$ref":"#/components/schemas/AttentionSeverity"},"message":{"type":"string","minLength":1,"maxLength":200},"link":{"$ref":"#/components/schemas/ChannelSettingsPath"}},"required":["kind","severity","message"],"additionalProperties":false},"inventory.channel-attention-reportedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.channel-attention-reported"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChannelAttentionItemEncoded"},"maxItems":20}},"required":["channelId","items"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.channel-disconnectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.channel-disconnected"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"}},"required":["channelId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"SrcId":{"type":"string","pattern":"^src_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A src-prefixed uuid, e.g. src_9f8c1c2e-0000-4000-8000-000000000000"},"SourceType":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,31}$","description":"The kind of legacy platform, a slug its app declares."},"SourceStatus":{"type":"string","enum":["connected","importing","mirroring","retired"],"description":"`connected` — the app holds working credentials, nothing is imported yet; `importing` — the first import is running; `mirroring` — the first import landed and the app keeps the core in step with the platform until go-live; `retired` — the app's installation was retired at go-live (enforced by auth-service, reported here for display), final"},"SourceDataKind":{"type":"string","enum":["products","locations","parties","orders","purchase-orders","stock-positions"],"description":"A kind of data a source's import brings: `products` (products and their SKUs), `locations` (warehouses and stores), `parties` (customers and suppliers), `orders` (open sales orders), `purchase-orders` (open purchase orders), `stock-positions` (stock on hand, one per SKU and site)"},"SourceCountEncoded":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/SourceDataKind"},"count":{"type":"integer","minimum":0}},"required":["kind","count"],"additionalProperties":false},"inventory.source-connectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.source-connected"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sourceId":{"$ref":"#/components/schemas/SrcId"},"appId":{"$ref":"#/components/schemas/AppId"},"type":{"$ref":"#/components/schemas/SourceType"},"name":{"type":"string","minLength":1},"status":{"$ref":"#/components/schemas/SourceStatus"},"counts":{"type":"array","items":{"$ref":"#/components/schemas/SourceCountEncoded"}}},"required":["sourceId","appId","type","name","status","counts"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.source-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.source-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sourceId":{"$ref":"#/components/schemas/SrcId"},"name":{"type":"string","minLength":1},"status":{"$ref":"#/components/schemas/SourceStatus"},"counts":{"type":"array","items":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/SourceDataKind"},"count":{"type":"integer","minimum":0}},"required":["kind","count"],"additionalProperties":false}}},"required":["sourceId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"TrfId":{"type":"string","pattern":"^trf_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A trf-prefixed uuid, e.g. trf_9f8c1c2e-0000-4000-8000-000000000000"},"inventory.transfer-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.transfer-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transferId":{"$ref":"#/components/schemas/TrfId"},"number":{"type":"string","minLength":1},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"reference":{"type":"string","minLength":1},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1}},"required":["transferId","number","fromLocationId","toLocationId","reference","lines"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.transfer-despatchedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.transfer-despatched"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transferId":{"$ref":"#/components/schemas/TrfId"},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1},"reference":{"type":"string","minLength":1}},"required":["transferId","fromLocationId","toLocationId","lines","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.transfer-receivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.transfer-received"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transferId":{"$ref":"#/components/schemas/TrfId"},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1},"reference":{"type":"string","minLength":1}},"required":["transferId","fromLocationId","toLocationId","lines","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.transfer-completedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.transfer-completed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transferId":{"$ref":"#/components/schemas/TrfId"},"number":{"type":"string","minLength":1},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"reference":{"type":"string","minLength":1},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1}},"required":["transferId","number","fromLocationId","toLocationId","reference","lines"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.transfer-cancelledEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.transfer-cancelled"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transferId":{"$ref":"#/components/schemas/TrfId"},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"reason":{"type":"string","minLength":1},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku_1"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1}},"required":["transferId","fromLocationId","toLocationId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"StkId":{"type":"string","pattern":"^stk_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A stk-prefixed uuid, e.g. stk_9f8c1c2e-0000-4000-8000-000000000000"},"StocktakeKind":{"type":"string","enum":["opening","periodic"],"description":"`opening` — the tenant's first stocktake: every stock SKU at every live location counted and valued, where the general ledger begins; `periodic` — every later one, whose variance posts as a write-down or a gain"},"inventory.stocktake-startedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stocktake-started"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"number":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/StocktakeKind"},"locationIds":{"type":"array","items":{"$ref":"#/components/schemas/LocId"}}},"required":["stocktakeId","number","kind","locationIds"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stocktake-countedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stocktake-counted"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"counts":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"counted":{"type":"integer","minimum":0}},"required":["sku","locationId","counted"],"additionalProperties":false}},"costs":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"unitCostCents":{"type":"number","minimum":0}},"required":["sku","unitCostCents"],"additionalProperties":false}}},"required":["stocktakeId","counts","costs"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stocktake-completedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stocktake-completed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"number":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/StocktakeKind"},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"before":{"type":"integer","minimum":0},"counted":{"type":"integer","minimum":0}},"required":["sku","locationId","before","counted"],"additionalProperties":false}},"costs":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"unitCostCents":{"type":"number","minimum":0}},"required":["sku","unitCostCents"],"additionalProperties":false}}},"required":["stocktakeId","number","kind","lines","costs"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.stocktake-cancelledEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.stocktake-cancelled"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"reason":{"type":"string"}},"required":["stocktakeId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"TransferPolicy":{"type":"string","enum":["unrestricted","instant","two-step","off"],"description":"`unrestricted` — the caller picks per transfer; `instant` — one call, no in-transit state; `two-step` — despatch then receive; `off` — no transfers at all"},"HomeCurrency":{"type":"string"},"WeightUnit":{"type":"string","enum":["g","kg","oz","lb"],"description":"The unit a tenant reads and types weights in — `g` (grams), `kg` (kilograms), `oz` (ounces) or `lb` (pounds); weights are stored in whole grams whatever it is"},"LengthUnit":{"type":"string","enum":["mm","cm","in"],"description":"The unit a tenant reads and types box dimensions in — `mm` (millimetres), `cm` (centimetres) or `in` (inches); dimensions are stored in whole millimetres whatever it is"},"inventory.settings-configuredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.settings-configured"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"transfers":{"$ref":"#/components/schemas/TransferPolicy"},"homeCurrency":{"$ref":"#/components/schemas/HomeCurrency"},"weightUnit":{"$ref":"#/components/schemas/WeightUnit"},"lengthUnit":{"$ref":"#/components/schemas/LengthUnit"},"skuAlphabet":{"$ref":"#/components/schemas/SkuAlphabet"}},"required":["transfers","homeCurrency","weightUnit","lengthUnit","skuAlphabet"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.home-currency-lockedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.home-currency-locked"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"homeCurrency":{"$ref":"#/components/schemas/HomeCurrency"}},"required":["homeCurrency"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"TaxRegion":{"type":"string","enum":["AU-GST","NZ-GST","UK-VAT","EU-VAT","none"],"description":"The tax system a tenant is registered under: `AU-GST`, `NZ-GST`, `UK-VAT`, `EU-VAT` (in the member state the settings name) or `none` (no tax is charged)"},"TaxNumber":{"type":"string","minLength":1,"maxLength":60,"pattern":"^\\S(?:.*\\S)?$","description":"A tax registration number (ABN, NZ GST number, VAT number) as the business writes it, up to 60 characters"},"TaxRate":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/TaxClass"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"description":"A rate in basis points (1000 = 10 %)"},"from":{"$ref":"#/components/schemas/IsoDay"}},"required":["class","rateBps","from"],"additionalProperties":false,"description":"A class's rate in basis points, effective from a day on (the tax point is the invoice date)"},"FinancialYearStart":{"type":"integer","minimum":1,"maximum":12,"description":"The month (1–12) the financial year starts in, on its first day: 7 for 1 July (Australia), 4 for 1 April, 1 for a calendar year — the day a change of accounting basis may take effect from"},"TimeZone":{"type":"string","maxLength":64},"PriceConvention":{"type":"string","enum":["inclusive","exclusive"],"description":"Whether a price already includes tax: `inclusive` (tax is inside the price) or `exclusive` (tax is added on top)"},"ChargeTaxClass":{"anyOf":[{"$ref":"#/components/schemas/TaxClass"},{"type":"string","enum":["follows-goods"]}],"description":"How a charge (shipping, a fee) is taxed: at a fixed `TaxClass`, or `follows-goods` — split across the order's lines' classes in proportion to their net (Australia: delivering GST-free goods is GST-free)"},"TaxSettings":{"type":"object","properties":{"region":{"$ref":"#/components/schemas/TaxRegion"},"country":{"$ref":"#/components/schemas/CountryCode"},"taxNumber":{"$ref":"#/components/schemas/TaxNumber"},"rates":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"financialYearStart":{"$ref":"#/components/schemas/FinancialYearStart"},"timeZone":{"$ref":"#/components/schemas/TimeZone"},"defaultConvention":{"$ref":"#/components/schemas/PriceConvention"},"chargeClass":{"$ref":"#/components/schemas/ChargeTaxClass"}},"required":["region","country","rates","financialYearStart","timeZone","defaultConvention","chargeClass"],"additionalProperties":false},"inventory.tax-settings-configuredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.tax-settings-configured"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"$ref":"#/components/schemas/TaxSettings"}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"AccountingBasis":{"type":"string","enum":["accrual","cash"],"description":"When the books recognise revenue, expenses and their tax: `accrual` (when the invoice or bill is issued) or `cash` (when the money for it moves)"},"inventory.accounting-basis-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.accounting-basis-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"basis":{"$ref":"#/components/schemas/AccountingBasis"},"from":{"$ref":"#/components/schemas/IsoDay"}},"required":["basis"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ViewId":{"type":"string","pattern":"^view_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A view-prefixed uuid, e.g. view_9f8c1c2e-0000-4000-8000-000000000000"},"ViewScreen":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z][a-z0-9-]*$","description":"the list the view belongs to, e.g. inventory"},"ViewFilterOperator":{"type":"string","enum":["is","is-not"],"description":"`is` — the value is one of the listed values; `is-not` — it is none of them"},"ViewFilter":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"operator":{"$ref":"#/components/schemas/ViewFilterOperator"},"values":{"type":"array","items":{"type":"string","maxLength":120}}},"required":["key","operator","values"],"additionalProperties":false},"ViewSort":{"type":"string","pattern":"^[a-zA-Z]+:(asc|desc)$","description":"column:asc|desc, in the screen's own column names"},"inventory.view-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.view-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"viewId":{"$ref":"#/components/schemas/ViewId"},"screen":{"$ref":"#/components/schemas/ViewScreen"},"label":{"type":"string","minLength":1,"maxLength":60},"query":{"type":"string","maxLength":120},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ViewFilter"}},"sort":{"$ref":"#/components/schemas/ViewSort"}},"required":["viewId","screen","label","query","filters"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.view-deletedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.view-deleted"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"viewId":{"$ref":"#/components/schemas/ViewId"}},"required":["viewId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"AcctId":{"type":"string","pattern":"^acct_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A acct-prefixed uuid, e.g. acct_9f8c1c2e-0000-4000-8000-000000000000"},"AccountName":{"type":"string","minLength":1,"maxLength":80},"AccountDescription":{"type":"string","maxLength":500},"inventory.account-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.account-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"accountId":{"$ref":"#/components/schemas/AcctId"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"name":{"$ref":"#/components/schemas/AccountName"},"description":{"$ref":"#/components/schemas/AccountDescription"},"managedBy":{"type":"object","properties":{"appId":{"$ref":"#/components/schemas/AppId"},"externalId":{"type":"string","minLength":1,"maxLength":100}},"required":["appId","externalId"],"additionalProperties":false},"archived":{"type":"boolean"}},"required":["accountId","code","name","description"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.account-deletedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.account-deleted"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"accountId":{"$ref":"#/components/schemas/AcctId"}},"required":["accountId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.chart-sync-requestedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.chart-sync-requested"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"appIds":{"type":"array","items":{"$ref":"#/components/schemas/AppId"}}},"required":["appIds"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"EditableProductStatus":{"type":"string","enum":["active","draft"],"description":"The status a create or an edit may set: `active` or `draft` (archiving is its own command)"},"ProductHandle":{"type":"string","maxLength":255,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"Tag":{"type":"string","pattern":"^\\S[\\s\\S]*\\S$|^\\S$|^$","minLength":1,"maxLength":256,"description":"one tag: trimmed, 1–256 characters; matched case-insensitively"},"ProductTags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"},"maxItems":250},"ProductSeo":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"description":{"type":"string","minLength":1,"maxLength":320}},"additionalProperties":false},"ProductOption":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"minItems":1}},"required":["name","values"],"additionalProperties":false},"SelectedOption":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","minLength":1,"maxLength":120}},"required":["name","value"],"additionalProperties":false},"Component":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"VariantKind":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["stocked"]}},"required":["_tag"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["composite"]},"components":{"type":"array","items":{"$ref":"#/components/schemas/Component"},"minItems":1},"barcodes":{"$ref":"#/components/schemas/Barcodes"},"hsCodes":{"$ref":"#/components/schemas/HsCodes"},"countryOfOrigin":{"$ref":"#/components/schemas/CountryCode"},"weightGrams":{"type":"integer","exclusiveMinimum":0},"packedSize":{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},"ownPackaging":{"type":"boolean"},"orderRules":{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false}},"required":["_tag","components"],"additionalProperties":false}],"description":"`stocked` — the variant's SKU is an inventory item (its trade codes, measurements and order rules are the item's); `composite` — the SKU is a kit assembled from `components`, each a stocked SKU in a fixed quantity per kit, carrying its own barcodes, HS codes, country of origin, weight, packed size, whether it ships in its own packaging and its order rules"},"inventory.product-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.product-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"status":{"$ref":"#/components/schemas/EditableProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"type":"string","minLength":1,"maxLength":120},"productType":{"type":"string","minLength":1,"maxLength":120},"category":{"type":"string","minLength":1,"maxLength":255},"tags":{"$ref":"#/components/schemas/ProductTags"},"seo":{"$ref":"#/components/schemas/ProductSeo"},"taxClass":{"$ref":"#/components/schemas/TaxClass"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"}},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"kind":{"$ref":"#/components/schemas/VariantKind"}},"required":["variantId","sku","options","kind"],"additionalProperties":false},"minItems":1}},"required":["productId","title","status","handle","options","variants"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.product-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.product-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"status":{"$ref":"#/components/schemas/EditableProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"productType":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"category":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"tags":{"$ref":"#/components/schemas/ProductTags"},"seo":{"anyOf":[{"$ref":"#/components/schemas/ProductSeo"},{"type":"null"}]},"taxClass":{"anyOf":[{"$ref":"#/components/schemas/TaxClass"},{"type":"null"}]}},"required":["productId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.product-archivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.product-archived"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"}},"required":["productId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.variant-addedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.variant-added"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"variant":{"type":"object","properties":{"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"kind":{"$ref":"#/components/schemas/VariantKind"}},"required":["variantId","sku","options","kind"],"additionalProperties":false}},"required":["productId","variant"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"Component_1":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku_1"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"inventory.variant-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.variant-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"components":{"type":"array","items":{"$ref":"#/components/schemas/Component_1"},"minItems":1},"barcodes":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BarcodeValue"},"type":{"$ref":"#/components/schemas/BarcodeType_1"}},"required":["value"],"additionalProperties":false},"maxItems":20},"hsCodes":{"type":"array","items":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode_1"},"code":{"$ref":"#/components/schemas/HsCode_1"}},"required":["code"],"additionalProperties":false},"maxItems":50},"countryOfOrigin":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"packedSize":{"anyOf":[{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},{"type":"null"}]},"ownPackaging":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"orderRules":{"anyOf":[{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},{"type":"null"}]}},"required":["productId","variantId","sku"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.variant-removedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.variant-removed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"}},"required":["productId","variantId","sku"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.product-options-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.product-options-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"}},"selections":{"type":"array","items":{"type":"object","properties":{"variantId":{"$ref":"#/components/schemas/VarId"},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}}},"required":["variantId","options"],"additionalProperties":false}}},"required":["productId","options","selections"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"CatalogPriceConvention":{"type":"string","enum":["inclusive","exclusive","tenant-default"],"description":"Whether a catalog's prices include tax: `inclusive`, `exclusive`, or `tenant-default` (the tenant's tax settings' `defaultConvention`)"},"inventory.catalog-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"taxInclusive":{"$ref":"#/components/schemas/CatalogPriceConvention"}},"required":["catalogId","name","currency"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-updatedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-updated"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"compareAtCatalogId":{"anyOf":[{"$ref":"#/components/schemas/CatId"},{"type":"null"}]},"taxInclusive":{"$ref":"#/components/schemas/CatalogPriceConvention"},"minimumMarginBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000},{"type":"null"}]}},"required":["catalogId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-archivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-archived"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"}},"required":["catalogId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-product-includedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-product-included"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"productId":{"$ref":"#/components/schemas/PrdId"}},"required":["catalogId","productId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-product-excludedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-product-excluded"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"productId":{"$ref":"#/components/schemas/PrdId"},"skus":{"type":"array","items":{"$ref":"#/components/schemas/Sku"}}},"required":["catalogId","productId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"PriceBreak":{"type":"object","properties":{"minQuantity":{"type":"integer","minimum":2},"priceCents":{"type":"integer","minimum":0}},"required":["minQuantity","priceCents"],"additionalProperties":false},"PriceBreaks":{"type":"array","items":{"$ref":"#/components/schemas/PriceBreak"}},"inventory.catalog-price-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-price-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"sku":{"$ref":"#/components/schemas/Sku"},"priceCents":{"type":"integer","minimum":0},"breaks":{"$ref":"#/components/schemas/PriceBreaks"}},"required":["catalogId","sku","priceCents"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-price-removedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-price-removed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"sku":{"$ref":"#/components/schemas/Sku"}},"required":["catalogId","sku"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-locations-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-locations-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"locationIds":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["catalogId","locationIds"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"PriceBase":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["catalog"]},"catalogId":{"$ref":"#/components/schemas/CatId"}},"required":["_tag","catalogId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["cost"]}},"required":["_tag"],"additionalProperties":false}]},"PriceAdjustment":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["markup"]},"basisPoints":{"type":"integer","exclusiveMinimum":0}},"required":["_tag","basisPoints"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["margin"]},"basisPoints":{"type":"integer","exclusiveMinimum":0,"exclusiveMaximum":10000}},"required":["_tag","basisPoints"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["discount"]},"basisPoints":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["_tag","basisPoints"],"additionalProperties":false}]},"CatalogPricing":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["manual"]}},"required":["_tag"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["auto"]},"base":{"$ref":"#/components/schemas/PriceBase"},"adjustment":{"$ref":"#/components/schemas/PriceAdjustment"},"rounding":{"type":"array","items":{"type":"object","properties":{"fromCents":{"type":"integer","minimum":0},"stepCents":{"type":"integer","exclusiveMinimum":0},"endingCents":{"type":"integer","minimum":0}},"required":["stepCents"],"additionalProperties":false},"minItems":1}},"required":["_tag","base"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["channel"]}},"required":["_tag"],"additionalProperties":false}]},"inventory.catalog-pricing-configuredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-pricing-configured"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"pricing":{"$ref":"#/components/schemas/CatalogPricing"}},"required":["catalogId","pricing"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"FxRate":{"type":"object","properties":{"base":{"$ref":"#/components/schemas/Currency"},"quote":{"$ref":"#/components/schemas/Currency"},"rateMicros":{"type":"integer","exclusiveMinimum":0},"windowStart":{"type":"string"}},"required":["base","quote","rateMicros","windowStart"],"additionalProperties":false},"inventory.fx-rate-recordedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.fx-rate-recorded"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"$ref":"#/components/schemas/FxRate"}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.sku-cost-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.sku-cost-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"costCents":{"type":"number","minimum":0}},"required":["sku","costCents"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"AstId":{"type":"string","pattern":"^ast_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ast-prefixed uuid, e.g. ast_9f8c1c2e-0000-4000-8000-000000000000"},"AssetOwner":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["sku"]},"sku":{"$ref":"#/components/schemas/Sku"}},"required":["_tag","sku"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["product"]},"productId":{"$ref":"#/components/schemas/PrdId"}},"required":["_tag","productId"],"additionalProperties":false}]},"AssetFilename":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/\\\\]+$","description":"The file's name as uploaded (no path)."},"AssetContentType":{"type":"string","pattern":"^[\\w.+-]+\\/[\\w.+-]+$","maxLength":120,"description":"A media type, e.g. `image/png`."},"inventory.asset-uploadedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.asset-uploaded"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"assetId":{"$ref":"#/components/schemas/AstId"},"owner":{"$ref":"#/components/schemas/AssetOwner"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"size":{"type":"integer","minimum":0},"reference":{"type":"string","minLength":1}},"required":["assetId","owner","filename","contentType","size","reference"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.asset-removedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.asset-removed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"assetId":{"$ref":"#/components/schemas/AstId"},"owner":{"$ref":"#/components/schemas/AssetOwner"}},"required":["assetId","owner"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"CgrId":{"type":"string","pattern":"^cgr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cgr-prefixed uuid, e.g. cgr_9f8c1c2e-0000-4000-8000-000000000000"},"CommissionRateBps":{"type":"integer","minimum":0,"maximum":10000,"description":"A commission rate in basis points, 0–10 000 (100 bps is 1%)"},"inventory.commission-group-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.commission-group-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"groupId":{"$ref":"#/components/schemas/CgrId"},"name":{"type":"string","minLength":1,"maxLength":80},"baseRateBps":{"$ref":"#/components/schemas/CommissionRateBps"},"description":{"type":"string","maxLength":500}},"required":["groupId","name","baseRateBps"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"GroupCatalogs":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["all"]}},"required":["_tag"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["listed"]},"catalogIds":{"type":"array","items":{"$ref":"#/components/schemas/CatId"},"maxItems":500}},"required":["_tag","catalogIds"],"additionalProperties":false}]},"inventory.commission-group-catalogs-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.commission-group-catalogs-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"groupId":{"$ref":"#/components/schemas/CgrId"},"catalogs":{"$ref":"#/components/schemas/GroupCatalogs"}},"required":["groupId","catalogs"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.commission-group-archivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.commission-group-archived"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"groupId":{"$ref":"#/components/schemas/CgrId"}},"required":["groupId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.commission-member-assignedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.commission-member-assigned"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"groupId":{"$ref":"#/components/schemas/CgrId"}},"required":["userId","groupId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"CommissionEarnedOn":{"type":"string","enum":["invoiced","paid","shipped"],"description":"When commission is earned, tenant-wide: `invoiced` (each invoice line, on the invoice's day — the default), `paid` (each payment's share of the order, on its day) or `shipped` (each shipped parcel's units, on the day it shipped)"},"CommissionEarner":{"type":"string","enum":["order-rep","account-manager"],"description":"Who earns an order's commission, tenant-wide: `order-rep` (the order's sales rep — the default) or `account-manager` (the account rep of the order's company, else its customer, when the order is placed; none is `unassigned` and earns nothing)"},"inventory.commission-settings-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.commission-settings-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"earnedOn":{"$ref":"#/components/schemas/CommissionEarnedOn"},"earner":{"$ref":"#/components/schemas/CommissionEarner"}},"required":["earnedOn","earner"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"GroupRate":{"type":"object","properties":{"groupId":{"$ref":"#/components/schemas/CgrId"},"rateBps":{"$ref":"#/components/schemas/CommissionRateBps"}},"required":["groupId","rateBps"],"additionalProperties":false},"CommissionRule":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["uncommissionable"]}},"required":["_tag"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["rates"]},"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupRate"},"minItems":1,"maxItems":100}},"required":["_tag","groups"],"additionalProperties":false}]},"inventory.catalog-commission-setEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-commission-set"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"sku":{"$ref":"#/components/schemas/Sku"},"rule":{"$ref":"#/components/schemas/CommissionRule"}},"required":["catalogId","sku","rule"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"inventory.catalog-commission-removedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["inventory.catalog-commission-removed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"sku":{"$ref":"#/components/schemas/Sku"}},"required":["catalogId","sku"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ItemEventPageEncoded":{"type":"object","properties":{"events":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/inventory.item-createdEncoded"},{"$ref":"#/components/schemas/inventory.item-updatedEncoded"},{"$ref":"#/components/schemas/inventory.stock-adjustedEncoded"},{"$ref":"#/components/schemas/inventory.stock-receivedEncoded"},{"$ref":"#/components/schemas/inventory.stock-identifiedEncoded"},{"$ref":"#/components/schemas/inventory.shortfall-recordedEncoded"},{"$ref":"#/components/schemas/inventory.stock-dispatchedEncoded"},{"$ref":"#/components/schemas/inventory.stock-damagedEncoded"},{"$ref":"#/components/schemas/inventory.stock-disposedEncoded"},{"$ref":"#/components/schemas/inventory.stock-reservedEncoded"},{"$ref":"#/components/schemas/inventory.stock-releasedEncoded"},{"$ref":"#/components/schemas/inventory.stock-returnedEncoded"},{"$ref":"#/components/schemas/inventory.incoming-expectedEncoded"},{"$ref":"#/components/schemas/inventory.incoming-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.location-createdEncoded"},{"$ref":"#/components/schemas/inventory.location-updatedEncoded"},{"$ref":"#/components/schemas/inventory.location-archivedEncoded"},{"$ref":"#/components/schemas/inventory.location-boundEncoded"},{"$ref":"#/components/schemas/inventory.location-unboundEncoded"},{"$ref":"#/components/schemas/inventory.channel-connectedEncoded"},{"$ref":"#/components/schemas/inventory.channel-updatedEncoded"},{"$ref":"#/components/schemas/inventory.channel-intake-reportedEncoded"},{"$ref":"#/components/schemas/inventory.channel-attention-reportedEncoded"},{"$ref":"#/components/schemas/inventory.channel-disconnectedEncoded"},{"$ref":"#/components/schemas/inventory.source-connectedEncoded"},{"$ref":"#/components/schemas/inventory.source-updatedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-createdEncoded"},{"$ref":"#/components/schemas/inventory.transfer-despatchedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-receivedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-completedEncoded"},{"$ref":"#/components/schemas/inventory.transfer-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-startedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-countedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-completedEncoded"},{"$ref":"#/components/schemas/inventory.stocktake-cancelledEncoded"},{"$ref":"#/components/schemas/inventory.settings-configuredEncoded"},{"$ref":"#/components/schemas/inventory.home-currency-lockedEncoded"},{"$ref":"#/components/schemas/inventory.tax-settings-configuredEncoded"},{"$ref":"#/components/schemas/inventory.accounting-basis-setEncoded"},{"$ref":"#/components/schemas/inventory.view-savedEncoded"},{"$ref":"#/components/schemas/inventory.view-deletedEncoded"},{"$ref":"#/components/schemas/inventory.account-savedEncoded"},{"$ref":"#/components/schemas/inventory.account-deletedEncoded"},{"$ref":"#/components/schemas/inventory.chart-sync-requestedEncoded"},{"$ref":"#/components/schemas/inventory.product-createdEncoded"},{"$ref":"#/components/schemas/inventory.product-updatedEncoded"},{"$ref":"#/components/schemas/inventory.product-archivedEncoded"},{"$ref":"#/components/schemas/inventory.variant-addedEncoded"},{"$ref":"#/components/schemas/inventory.variant-updatedEncoded"},{"$ref":"#/components/schemas/inventory.variant-removedEncoded"},{"$ref":"#/components/schemas/inventory.product-options-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-createdEncoded"},{"$ref":"#/components/schemas/inventory.catalog-updatedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-archivedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-product-includedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-product-excludedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-price-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-price-removedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-locations-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-pricing-configuredEncoded"},{"$ref":"#/components/schemas/inventory.fx-rate-recordedEncoded"},{"$ref":"#/components/schemas/inventory.sku-cost-setEncoded"},{"$ref":"#/components/schemas/inventory.asset-uploadedEncoded"},{"$ref":"#/components/schemas/inventory.asset-removedEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-savedEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-catalogs-setEncoded"},{"$ref":"#/components/schemas/inventory.commission-group-archivedEncoded"},{"$ref":"#/components/schemas/inventory.commission-member-assignedEncoded"},{"$ref":"#/components/schemas/inventory.commission-settings-savedEncoded"},{"$ref":"#/components/schemas/inventory.catalog-commission-setEncoded"},{"$ref":"#/components/schemas/inventory.catalog-commission-removedEncoded"}]}},"next":{"type":"integer","minimum":0}},"required":["events"],"additionalProperties":false},"IncomingExpectationEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"poId":{"$ref":"#/components/schemas/PoId"},"quantity":{"type":"integer","minimum":0},"locationId":{"$ref":"#/components/schemas/LocId"},"since":{"type":"string"}},"required":["sku","poId","quantity","locationId","since"],"additionalProperties":false},"IncomingPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IncomingExpectationEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"BackorderDemandEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"orderId":{"$ref":"#/components/schemas/OrdId"},"quantity":{"type":"integer","minimum":0},"since":{"type":"string"}},"required":["sku","orderId","quantity","since"],"additionalProperties":false},"BackorderPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BackorderDemandEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"AdjustStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"delta":{"type":"integer"},"reason":{"$ref":"#/components/schemas/AdjustReason"},"reference":{"type":"string","minLength":1}},"required":["delta","reason","reference"],"additionalProperties":false},"InsufficientStockEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["InsufficientStock"]},"sku":{"type":"string"},"available":{"type":"integer"},"requested":{"type":"integer"},"locationId":{"$ref":"#/components/schemas/LocId"}},"required":["_tag","sku","available","requested"],"additionalProperties":false},"ReceiveStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"poId":{"$ref":"#/components/schemas/PoId"},"unitCostCents":{"type":"number","minimum":0},"costCurrency":{"$ref":"#/components/schemas/CurrencyCode"},"reference":{"type":"string","minLength":1}},"required":["quantity","reference"],"additionalProperties":false},"CurrencyUnsupportedReason":{"type":"string","enum":["unquoted","no-rate"],"description":"`unquoted`: no bank Manifold keeps rates from publishes the currency; `no-rate`: none published it in the fortnight before the day asked about"},"ReferenceRateUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ReferenceRateUnavailable"]},"currency":{"type":"string"},"homeCurrency":{"type":"string"},"date":{"type":"string"},"reason":{"$ref":"#/components/schemas/CurrencyUnsupportedReason"}},"required":["_tag","currency","homeCurrency","date","reason"],"additionalProperties":false},"DamageStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"reference":{"type":"string","minLength":1}},"required":["quantity","reference"],"additionalProperties":false},"DisposeStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"bucket":{"$ref":"#/components/schemas/DisposeBucket"},"reference":{"type":"string","minLength":1}},"required":["quantity","reference"],"additionalProperties":false},"DispatchStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["quantity","reference"],"additionalProperties":false},"LocationNotFulfillableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationNotFulfillable"]},"locationId":{"type":"string"}},"required":["_tag","locationId"],"additionalProperties":false},"ReserveStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["quantity","orderId","reference"],"additionalProperties":false},"ReleaseStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1}},"required":["quantity","orderId","reference"],"additionalProperties":false},"ReturnStockEncoded":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"quantity":{"type":"integer","exclusiveMinimum":0},"orderId":{"$ref":"#/components/schemas/OrdId"},"reference":{"type":"string","minLength":1},"condition":{"$ref":"#/components/schemas/ReturnCondition"}},"required":["quantity","reference","condition"],"additionalProperties":false},"ExpectIncomingEncoded":{"type":"object","properties":{"poId":{"$ref":"#/components/schemas/PoId"},"quantity":{"type":"integer","exclusiveMinimum":0},"locationId":{"$ref":"#/components/schemas/LocId"},"reference":{"type":"string","minLength":1}},"required":["poId","quantity","reference"],"additionalProperties":false},"CancelIncomingEncoded":{"type":"object","properties":{"poId":{"$ref":"#/components/schemas/PoId"},"reference":{"type":"string","minLength":1}},"required":["poId","reference"],"additionalProperties":false},"IdentifyStockEncoded":{"type":"object","properties":{"quantity":{"type":"integer","exclusiveMinimum":0},"locationId":{"$ref":"#/components/schemas/LocId"},"serials":{"type":"array","items":{"$ref":"#/components/schemas/SerialNumber"},"minItems":1},"batchNumber":{"$ref":"#/components/schemas/BatchNumber"},"expiresAt":{"type":"string"},"reference":{"type":"string","minLength":1}},"required":["quantity","reference"],"additionalProperties":false},"NothingAwaitingIdentificationEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["NothingAwaitingIdentification"]},"sku":{"type":"string"},"awaiting":{"type":"integer"},"requested":{"type":"integer"}},"required":["_tag","sku","awaiting","requested"],"additionalProperties":false},"IdentityTrackingMismatchEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["IdentityTrackingMismatch"]},"sku":{"type":"string"},"tracking":{"$ref":"#/components/schemas/Tracking"},"reason":{"type":"string"}},"required":["_tag","sku","tracking","reason"],"additionalProperties":false},"RecordShortfallEncoded":{"type":"object","properties":{"orderId":{"$ref":"#/components/schemas/OrdId"},"quantity":{"type":"integer","minimum":0}},"required":["orderId","quantity"],"additionalProperties":false},"ShortSku":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string"},"projected":{"type":"integer"},"available":{"type":"integer"},"incoming":{"type":"integer"},"backordered":{"type":"integer"}},"required":["sku","name","projected","available","incoming","backordered"],"additionalProperties":false},"LocationCount":{"type":"object","properties":{"locationId":{"$ref":"#/components/schemas/LocId"},"name":{"type":"string"},"lastCountedAt":{"type":"string"}},"required":["locationId","name"],"additionalProperties":false},"StockAttentionEncoded":{"type":"object","properties":{"shortSkus":{"type":"integer","minimum":0},"short":{"type":"array","items":{"$ref":"#/components/schemas/ShortSku"}},"counts":{"type":"array","items":{"$ref":"#/components/schemas/LocationCount"}}},"required":["shortSkus","short","counts"],"additionalProperties":false},"GeoPoint_2":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["latitude","longitude"],"additionalProperties":false,"description":"A point on the earth in decimal degrees (WGS 84): where a geocoder placed an address."},"LocationBindingEncoded":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/ChnId"},"externalId":{"type":"string","minLength":1},"externalName":{"type":"string","maxLength":255}},"required":["channelId","externalId","externalName"],"additionalProperties":false},"LocationEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/LocId"},"name":{"type":"string","minLength":1,"maxLength":120},"fulfillable":{"type":"boolean"},"archived":{"type":"boolean"},"note":{"type":"string","maxLength":500},"address":{"$ref":"#/components/schemas/PostalAddress"},"coordinates":{"$ref":"#/components/schemas/GeoPoint_2"},"rank":{"$ref":"#/components/schemas/LocationRank"},"bindings":{"type":"array","items":{"$ref":"#/components/schemas/LocationBindingEncoded"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","fulfillable","createdAt","updatedAt"],"additionalProperties":false},"LocationPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LocationEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"CreateLocationEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"fulfillable":{"type":"boolean"},"note":{"type":"string","maxLength":500},"address":{"$ref":"#/components/schemas/PostalAddress"},"rank":{"$ref":"#/components/schemas/LocationRank"}},"required":["name"],"additionalProperties":false},"LocationNameConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationNameConflict"]},"name":{"type":"string"}},"required":["_tag","name"],"additionalProperties":false},"UpdateLocationEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"fulfillable":{"type":"boolean"},"note":{"type":"string","maxLength":500},"address":{"$ref":"#/components/schemas/PostalAddress"},"rank":{"$ref":"#/components/schemas/LocationRank"}},"additionalProperties":false},"LastFulfillableLocationEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LastFulfillableLocation"]},"locationId":{"type":"string"}},"required":["_tag","locationId"],"additionalProperties":false},"SetLocationPriorityEncoded":{"type":"object","properties":{"locationIds":{"type":"array","items":{"$ref":"#/components/schemas/LocId"},"minItems":1,"maxItems":500}},"required":["locationIds"],"additionalProperties":false},"LocationNotEmptyEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationNotEmpty"]},"locationId":{"type":"string"},"skus":{"type":"array","items":{"type":"string"}}},"required":["_tag","locationId","skus"],"additionalProperties":false},"LocationBoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LocationBound"]},"locationId":{"type":"string"},"channelIds":{"type":"array","items":{"type":"string"}}},"required":["_tag","locationId","channelIds"],"additionalProperties":false},"BindLocationEncoded":{"type":"object","properties":{"externalId":{"type":"string","minLength":1},"externalName":{"type":"string","maxLength":255}},"required":["externalId","externalName"],"additionalProperties":false},"ChannelNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChannelNotFound"]},"channelId":{"type":"string"}},"required":["_tag","channelId"],"additionalProperties":false},"ChannelNotConnectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChannelNotConnected"]},"channelId":{"type":"string"}},"required":["_tag","channelId"],"additionalProperties":false},"ProductSortKey":{"type":"string","enum":["title","status","createdAt","updatedAt"],"description":"The column the products grid is ordered by (master-data columns only)"},"ProductStatus":{"type":"string","enum":["active","draft","archived"],"description":"Where a product stands: `active` — offered to the channels that list it; `draft` — being prepared, offered nowhere; `archived` — withdrawn for good"},"ProductTags_1":{"type":"array","items":{"$ref":"#/components/schemas/Tag"},"maxItems":250},"VariantEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"kind":{"$ref":"#/components/schemas/VariantKind"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sku","options","kind","createdAt","updatedAt"],"additionalProperties":false},"ProductEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PrdId"},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"status":{"$ref":"#/components/schemas/ProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"type":"string","minLength":1,"maxLength":120},"productType":{"type":"string","minLength":1,"maxLength":120},"category":{"type":"string","minLength":1,"maxLength":255},"tags":{"$ref":"#/components/schemas/ProductTags_1"},"seo":{"$ref":"#/components/schemas/ProductSeo"},"taxClass":{"$ref":"#/components/schemas/TaxClass"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"},"maxItems":3},"variants":{"type":"array","items":{"$ref":"#/components/schemas/VariantEncoded"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","status","handle","options","variants","createdAt","updatedAt"],"additionalProperties":false},"ProductPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"ProductNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ProductNotFound"]},"productId":{"type":"string"}},"required":["_tag","productId"],"additionalProperties":false},"CreateVariantEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"kind":{"$ref":"#/components/schemas/VariantKind"}},"required":["sku"],"additionalProperties":false},"CreateProductEncoded":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"status":{"$ref":"#/components/schemas/EditableProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"type":"string","minLength":1,"maxLength":120},"productType":{"type":"string","minLength":1,"maxLength":120},"category":{"type":"string","minLength":1,"maxLength":255},"tags":{"$ref":"#/components/schemas/ProductTags_1"},"seo":{"$ref":"#/components/schemas/ProductSeo"},"taxClass":{"$ref":"#/components/schemas/TaxClass"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"},"maxItems":3},"variants":{"type":"array","items":{"$ref":"#/components/schemas/CreateVariantEncoded"},"minItems":1,"maxItems":100}},"required":["title","variants"],"additionalProperties":false},"VariantSkuConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["VariantSkuConflict"]},"sku":{"type":"string"},"productId":{"type":"string"}},"required":["_tag","sku","productId"],"additionalProperties":false},"SkuNotStockedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuNotStocked"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"CompositeSkuIsStockedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CompositeSkuIsStocked"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"VariantOptionsInvalidEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["VariantOptionsInvalid"]},"productId":{"type":"string"},"sku":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","productId","sku","reason"],"additionalProperties":false},"UpdateProductEncoded":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"status":{"$ref":"#/components/schemas/EditableProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"productType":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"category":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"tags":{"$ref":"#/components/schemas/ProductTags"},"seo":{"anyOf":[{"$ref":"#/components/schemas/ProductSeo"},{"type":"null"}]},"taxClass":{"anyOf":[{"$ref":"#/components/schemas/TaxClass"},{"type":"null"}]}},"additionalProperties":false},"ProductArchivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ProductArchived"]},"productId":{"type":"string"}},"required":["_tag","productId"],"additionalProperties":false},"SetProductOptionsEncoded":{"type":"object","properties":{"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"},"maxItems":3},"variants":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}}},"required":["sku","options"],"additionalProperties":false}}},"required":["options"],"additionalProperties":false},"VariantNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["VariantNotFound"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"UpdateVariantEncoded":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"components":{"type":"array","items":{"$ref":"#/components/schemas/Component_1"},"minItems":1},"barcodes":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BarcodeValue"},"type":{"$ref":"#/components/schemas/BarcodeType_1"}},"required":["value"],"additionalProperties":false},"maxItems":20},"hsCodes":{"type":"array","items":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode_1"},"code":{"$ref":"#/components/schemas/HsCode_1"}},"required":["code"],"additionalProperties":false},"maxItems":50},"countryOfOrigin":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"packedSize":{"anyOf":[{"type":"object","properties":{"lengthMm":{"type":"integer","exclusiveMinimum":0},"widthMm":{"type":"integer","exclusiveMinimum":0},"heightMm":{"type":"integer","exclusiveMinimum":0}},"required":["lengthMm","widthMm","heightMm"],"additionalProperties":false},{"type":"null"}]},"ownPackaging":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"orderRules":{"anyOf":[{"type":"object","properties":{"minQuantity":{"type":"integer","exclusiveMinimum":0},"step":{"type":"integer","exclusiveMinimum":0}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"VariantNotCompositeEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["VariantNotComposite"]},"sku":{"type":"string"}},"required":["_tag","sku"],"additionalProperties":false},"LastVariantEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["LastVariant"]},"productId":{"type":"string"},"sku":{"type":"string"}},"required":["_tag","productId","sku"],"additionalProperties":false},"ProductAvailabilityEncoded":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/VariantAvailabilityEncoded"}},"asOf":{"type":"string"}},"required":["productId","variants","asOf"],"additionalProperties":false},"AssetViewEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AstId"},"owner":{"$ref":"#/components/schemas/AssetOwner"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"size":{"type":"integer","minimum":0},"uploadedAt":{"type":"string"},"url":{"type":"string"},"urlExpiresAt":{"type":"string"}},"required":["id","owner","filename","contentType","size","uploadedAt","url","urlExpiresAt"],"additionalProperties":false},"AssetStoreUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AssetStoreUnavailable"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"AssetNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AssetNotFound"]},"assetId":{"type":"string"}},"required":["_tag","assetId"],"additionalProperties":false},"AssetTooLargeEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AssetTooLarge"]},"limit":{"type":"integer"},"size":{"type":"integer"}},"required":["_tag","limit"],"additionalProperties":false},"AssetUnreadableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AssetUnreadable"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"AssetEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AstId"},"owner":{"$ref":"#/components/schemas/AssetOwner"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"size":{"type":"integer","minimum":0},"uploadedAt":{"type":"string"}},"required":["id","owner","filename","contentType","size","uploadedAt"],"additionalProperties":false},"AssetOwnerScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AssetOwnerScopeRequired"]},"assetId":{"type":"string"},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","assetId","required"],"additionalProperties":false},"CatalogSortKey":{"type":"string","enum":["name","currency","status","createdAt","updatedAt"],"description":"The column the catalogs grid is ordered by"},"CatalogStatus":{"type":"string","enum":["active","archived"],"description":"`active` — in use; `archived` — withdrawn for good, resolves to no products"},"CatalogEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CatId"},"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"status":{"$ref":"#/components/schemas/CatalogStatus"},"productCount":{"type":"integer","minimum":0},"priceCount":{"type":"integer","minimum":0},"pricing":{"$ref":"#/components/schemas/CatalogPricing"},"compareAtCatalogId":{"$ref":"#/components/schemas/CatId"},"taxInclusive":{"$ref":"#/components/schemas/CatalogPriceConvention"},"minimumMarginBps":{"type":"integer","minimum":0,"maximum":10000},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","currency","status","productCount","priceCount","createdAt","updatedAt"],"additionalProperties":false},"CatalogPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"CatalogListingEncoded":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"}},"required":["productId"],"additionalProperties":false},"CatalogListingPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogListingEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"CatalogPrice":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"priceCents":{"type":"integer","minimum":0},"breaks":{"$ref":"#/components/schemas/PriceBreaks"},"auto":{"type":"boolean","enum":[true]},"compareAtCents":{"type":"integer","minimum":0}},"required":["sku","priceCents"],"additionalProperties":false},"CatalogPricePageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"ProductCatalogEntryEncoded":{"type":"object","properties":{"catalog":{"$ref":"#/components/schemas/CatalogEncoded"},"listed":{"type":"boolean"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["catalog","listed","prices"],"additionalProperties":false},"ProductCatalogsEncoded":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/ProductCatalogEntryEncoded"}}},"required":["productId","catalogs"],"additionalProperties":false},"CreateCatalogEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"taxInclusive":{"$ref":"#/components/schemas/CatalogPriceConvention"}},"required":["name","currency"],"additionalProperties":false},"CatalogNameConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CatalogNameConflict"]},"name":{"type":"string"}},"required":["_tag","name"],"additionalProperties":false},"UpdateCatalogEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"compareAtCatalogId":{"anyOf":[{"$ref":"#/components/schemas/CatId"},{"type":"null"}]},"taxInclusive":{"$ref":"#/components/schemas/CatalogPriceConvention"},"minimumMarginBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000},{"type":"null"}]}},"additionalProperties":false},"CatalogArchivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CatalogArchived"]},"catalogId":{"type":"string"}},"required":["_tag","catalogId"],"additionalProperties":false},"CompareAtCatalogInvalidEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CompareAtCatalogInvalid"]},"catalogId":{"$ref":"#/components/schemas/CatId"},"reason":{"type":"string"}},"required":["_tag","catalogId","reason"],"additionalProperties":false},"CatalogCurrencyFixedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CatalogCurrencyFixed"]},"catalogId":{"$ref":"#/components/schemas/CatId"},"currency":{"$ref":"#/components/schemas/Currency"},"reason":{"type":"string"}},"required":["_tag","catalogId","currency","reason"],"additionalProperties":false},"CatalogPricingInvalidEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CatalogPricingInvalid"]},"catalogId":{"$ref":"#/components/schemas/CatId"},"reason":{"type":"string"}},"required":["_tag","catalogId","reason"],"additionalProperties":false},"RecordFxRateEncoded":{"type":"object","properties":{"base":{"$ref":"#/components/schemas/Currency"},"quote":{"$ref":"#/components/schemas/Currency"},"rateMicros":{"type":"integer","exclusiveMinimum":0},"windowStart":{"type":"string"}},"required":["base","quote","rateMicros","windowStart"],"additionalProperties":false},"SetCatalogPriceEncoded":{"type":"object","properties":{"priceCents":{"type":"integer","minimum":0},"breaks":{"$ref":"#/components/schemas/PriceBreaks"}},"required":["priceCents"],"additionalProperties":false},"PriceForUnlistedSkuEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PriceForUnlistedSku"]},"catalogId":{"type":"string"},"sku":{"type":"string"}},"required":["_tag","catalogId","sku"],"additionalProperties":false},"CatalogViewVariantEncoded":{"type":"object","properties":{"variantId":{"$ref":"#/components/schemas/VarId"},"sku":{"$ref":"#/components/schemas/Sku"},"title":{"type":"string","minLength":1,"maxLength":200},"options":{"type":"array","items":{"$ref":"#/components/schemas/SelectedOption"}},"kind":{"$ref":"#/components/schemas/VariantKindTag"},"priceCents":{"type":"integer","minimum":0}},"required":["variantId","sku","options","kind"],"additionalProperties":false},"CatalogViewProductEncoded":{"type":"object","properties":{"productId":{"$ref":"#/components/schemas/PrdId"},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/EditableProductStatus"},"handle":{"$ref":"#/components/schemas/ProductHandle"},"vendor":{"type":"string","minLength":1,"maxLength":120},"productType":{"type":"string","minLength":1,"maxLength":120},"category":{"type":"string","minLength":1,"maxLength":255},"tags":{"$ref":"#/components/schemas/ProductTags_1"},"seo":{"$ref":"#/components/schemas/ProductSeo"},"taxClass":{"$ref":"#/components/schemas/TaxClass"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOption"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogViewVariantEncoded"}}},"required":["productId","title","status","handle","options","variants"],"additionalProperties":false},"CatalogViewEncoded":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"name":{"type":"string","minLength":1,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"products":{"type":"array","items":{"$ref":"#/components/schemas/CatalogViewProductEncoded"}}},"required":["catalogId","name","currency","products"],"additionalProperties":false},"StockSettingsEncoded":{"type":"object","properties":{"transfers":{"$ref":"#/components/schemas/TransferPolicy"},"homeCurrency":{"$ref":"#/components/schemas/HomeCurrency"},"homeCurrencyLocked":{"type":"boolean"},"weightUnit":{"$ref":"#/components/schemas/WeightUnit"},"lengthUnit":{"$ref":"#/components/schemas/LengthUnit"},"skuAlphabet":{"$ref":"#/components/schemas/SkuAlphabet"}},"additionalProperties":false},"HomeCurrencyLockedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["HomeCurrencyLocked"]},"homeCurrency":{"type":"string"}},"required":["_tag","homeCurrency"],"additionalProperties":false},"SkuAlphabetInUseEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SkuAlphabetInUse"]},"alphabet":{"$ref":"#/components/schemas/SkuAlphabet"},"skus":{"type":"array","items":{"type":"string"}}},"required":["_tag","alphabet","skus"],"additionalProperties":false},"BasisChangeProblem":{"type":"string","enum":["day-required","day-not-allowed","not-a-year-start","not-after-today","too-soon"],"description":"Why a change of basis was refused: `day-required` — the books are open, so a change needs the day it takes effect; `day-not-allowed` — the books are not open yet, so the basis they open on is set without a day; `not-a-year-start` — the day is not the first of a financial year; `not-after-today` — the day is today or past in the books' zone; `too-soon` — the last change was made less than a week ago (`changeableFrom` says when the next may be)"},"BasisChangeRefusedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["BasisChangeRefused"]},"problem":{"$ref":"#/components/schemas/BasisChangeProblem"},"changeDays":{"type":"array","items":{"$ref":"#/components/schemas/IsoDay"}},"changeableFrom":{"type":"string"}},"required":["_tag","problem","changeDays"],"additionalProperties":false},"BasisChange":{"type":"object","properties":{"basis":{"$ref":"#/components/schemas/AccountingBasis"},"from":{"$ref":"#/components/schemas/IsoDay"}},"required":["basis","from"],"additionalProperties":false,"description":"From `from` (the first day of a financial year, from midnight in the books' zone — the tax settings' `timeZone`) on, the books are kept on `basis`"},"AccountingBasisSchedule":{"type":"object","properties":{"opening":{"$ref":"#/components/schemas/AccountingBasis"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/BasisChange"}},"changedAt":{"type":"string"}},"required":["opening","changes"],"additionalProperties":false,"description":"The basis the books open on, then each change of basis with the day it takes effect, earliest first"},"AccountingBasisSettingsEncoded":{"type":"object","properties":{"basis":{"$ref":"#/components/schemas/AccountingBasis"},"since":{"$ref":"#/components/schemas/IsoDay"},"scheduled":{"$ref":"#/components/schemas/BasisChange"},"booksOpen":{"type":"boolean"},"financialYearStart":{"$ref":"#/components/schemas/FinancialYearStart"},"changeDays":{"type":"array","items":{"$ref":"#/components/schemas/IsoDay"}},"changeableFrom":{"type":"string"},"schedule":{"$ref":"#/components/schemas/AccountingBasisSchedule"}},"required":["basis","booksOpen","financialYearStart","changeDays","schedule"],"additionalProperties":false},"SetAccountingBasisEncoded":{"type":"object","properties":{"basis":{"$ref":"#/components/schemas/AccountingBasis"},"from":{"$ref":"#/components/schemas/IsoDay"}},"required":["basis"],"additionalProperties":false},"FxSource":{"type":"string","enum":["rba","rbnz","ecb","boe","fed","boc","norges-bank","nationalbanken"],"description":"The central bank a conversion's rate is from: `rba`, `rbnz`, `ecb`, `boe`, `fed` (H.10), `boc`, `norges-bank`, `nationalbanken` (Danmarks Nationalbank)"},"ReferenceRateEncoded":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"homeCurrency":{"$ref":"#/components/schemas/Currency"},"date":{"$ref":"#/components/schemas/IsoDay"},"rate":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"rateDate":{"$ref":"#/components/schemas/IsoDay"},"source":{"$ref":"#/components/schemas/FxSource"},"via":{"$ref":"#/components/schemas/Currency"}},"required":["currency","homeCurrency","date","rate","rateDate"],"additionalProperties":false},"IndexViewEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ViewId"},"screen":{"$ref":"#/components/schemas/ViewScreen"},"label":{"type":"string","minLength":1,"maxLength":60},"query":{"type":"string","maxLength":120},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ViewFilter"}},"sort":{"$ref":"#/components/schemas/ViewSort"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","screen","label","query","filters","createdAt","updatedAt"],"additionalProperties":false},"SaveIndexViewEncoded":{"type":"object","properties":{"screen":{"$ref":"#/components/schemas/ViewScreen"},"label":{"type":"string","minLength":1,"maxLength":60},"query":{"type":"string","maxLength":120},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ViewFilter"}},"sort":{"$ref":"#/components/schemas/ViewSort"}},"required":["screen","label"],"additionalProperties":false},"UpdateIndexViewEncoded":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":60},"query":{"type":"string","maxLength":120},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ViewFilter"}},"sort":{"anyOf":[{"$ref":"#/components/schemas/ViewSort"},{"type":"string","enum":[""]}]}},"additionalProperties":false},"ViewNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ViewNotFound"]},"viewId":{"type":"string"}},"required":["_tag","viewId"],"additionalProperties":false},"LedgerRole":{"type":"string","enum":["channel-payments-clearing","paypal-clearing","stripe-clearing","other-provider-clearing","provider-reserves","undeposited-funds","supplier-payments-clearing","receivables","accounts-payable","goods-received-not-invoiced","carrier-charges-accrued","accrued-costs","tax-payable","gift-card-liability","customer-credit","sales-awaiting-payment","bills-awaiting-payment","opening-balances","shipping-income","discounts","refunds","write-downs","shipping-costs","payment-fees","credit-given","realised-exchange","unrealised-exchange"],"description":"A control account the general ledger posts to that no SKU chooses — the other side of every sale, payment, receipt and write-down; each role posts to one fixed code (`LEDGER_ACCOUNTS`)"},"ChartAccountSummaryEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AcctId"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"name":{"$ref":"#/components/schemas/AccountName"},"description":{"$ref":"#/components/schemas/AccountDescription"},"managedBy":{"type":"object","properties":{"appId":{"$ref":"#/components/schemas/AppId"},"externalId":{"type":"string","minLength":1,"maxLength":100}},"required":["appId","externalId"],"additionalProperties":false},"archived":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"skus":{"type":"integer","minimum":0},"defaultFor":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/AccountRole"},{"$ref":"#/components/schemas/LedgerRole"}]}}},"required":["id","code","name","description","createdAt","updatedAt","skus","defaultFor"],"additionalProperties":false},"CreateChartAccountEncoded":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"name":{"$ref":"#/components/schemas/AccountName"},"description":{"$ref":"#/components/schemas/AccountDescription"}},"required":["code","name"],"additionalProperties":false},"ChartAccountEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AcctId"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"name":{"$ref":"#/components/schemas/AccountName"},"description":{"$ref":"#/components/schemas/AccountDescription"},"managedBy":{"type":"object","properties":{"appId":{"$ref":"#/components/schemas/AppId"},"externalId":{"type":"string","minLength":1,"maxLength":100}},"required":["appId","externalId"],"additionalProperties":false},"archived":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","code","name","description","createdAt","updatedAt"],"additionalProperties":false},"AccountCodeConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AccountCodeConflict"]},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"}},"required":["_tag","code"],"additionalProperties":false},"UpdateChartAccountEncoded":{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"integer"}]},"name":{"$ref":"#/components/schemas/AccountName"},"description":{"$ref":"#/components/schemas/AccountDescription"}},"additionalProperties":false},"ChartAccountNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChartAccountNotFound"]},"accountId":{"type":"string"}},"required":["_tag","accountId"],"additionalProperties":false},"AccountInUseEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AccountInUse"]},"accountId":{"type":"string"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"skus":{"type":"integer"}},"required":["_tag","accountId","code","skus"],"additionalProperties":false},"DefaultAccountProtectedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["DefaultAccountProtected"]},"accountId":{"type":"string"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"roles":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/AccountRole"},{"$ref":"#/components/schemas/LedgerRole"}]}}},"required":["_tag","accountId","code","roles"],"additionalProperties":false},"AccountManagedByAppEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AccountManagedByApp"]},"accountId":{"type":"string"},"code":{"$ref":"#/components/schemas/AccountCodeEncoded"},"appId":{"$ref":"#/components/schemas/AppId"}},"required":["_tag","accountId","code","appId"],"additionalProperties":false},"ManagedAccountEncoded":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":100},"code":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":500},"description":{"type":"string","maxLength":4000},"archived":{"type":"boolean"}},"required":["externalId","code","name","archived"],"additionalProperties":false},"SyncManagedAccountsEncoded":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccountEncoded"},"maxItems":5000}},"required":["accounts"],"additionalProperties":false},"ManagedAccountOutcome":{"type":"string","enum":["created","claimed","updated","unchanged","archived","skipped"],"description":"`created` — a new account in the chart; `claimed` — an account already at that code, now kept by the app; `updated` — renamed, renumbered or archived to match the app; `unchanged` — already as the app has it; `archived` — kept by the app but no longer in its chart, so marked archived; `skipped` — not taken, see `reason`"},"ManagedAccountResultEncoded":{"type":"object","properties":{"externalId":{"type":"string"},"code":{"type":"string"},"outcome":{"$ref":"#/components/schemas/ManagedAccountOutcome"},"accountId":{"$ref":"#/components/schemas/AcctId"},"reason":{"type":"string"}},"required":["externalId","code","outcome"],"additionalProperties":false},"ManagedAccountsSyncEncoded":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccountResultEncoded"}}},"required":["results"],"additionalProperties":false},"NotALedgerAppEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["NotALedgerApp"]}},"required":["_tag"],"additionalProperties":false},"ManagedAccountsReleasedEncoded":{"type":"object","properties":{"released":{"type":"array","items":{"$ref":"#/components/schemas/AcctId"}}},"required":["released"],"additionalProperties":false},"ChartSyncRequestedEncoded":{"type":"object","properties":{"appIds":{"type":"array","items":{"$ref":"#/components/schemas/AppId"}}},"required":["appIds"],"additionalProperties":false},"ChartNotManagedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChartNotManaged"]}},"required":["_tag"],"additionalProperties":false},"ChannelStatus":{"type":"string","enum":["connected","disconnected"],"description":"`connected` — the channel sells: its publications and location bindings are in force; `disconnected` — its app let it go (the store uninstalled, the account closed): history is kept, its bindings hold no site, and connecting it again restores it"},"ChannelOrderUrl":{"type":"string","maxLength":500},"ChannelCurrency":{"type":"string"},"ChannelSettingsPath_1":{"type":"string","maxLength":200,"pattern":"^(\\/[A-Za-z0-9_-]+)+$","description":"A path in the admin where the channel is configured, e.g. `/settings/channels/<type>/conn_…`."},"ChannelCollectionEncoded":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ChannelCollectionKind"},"state":{"$ref":"#/components/schemas/ChannelCapabilityState"},"processor":{"type":"string","minLength":1,"maxLength":200},"note":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","state","processor"],"additionalProperties":false},"ChannelEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ChnId"},"appId":{"$ref":"#/components/schemas/AppId"},"type":{"$ref":"#/components/schemas/ChannelType"},"externalId":{"type":"string","minLength":1,"maxLength":255},"name":{"type":"string","minLength":1,"maxLength":120},"status":{"$ref":"#/components/schemas/ChannelStatus"},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/ChannelPublicationEncoded"}},"orderUrl":{"$ref":"#/components/schemas/ChannelOrderUrl"},"settingsPath":{"$ref":"#/components/schemas/ChannelSettingsPath"},"currency":{"$ref":"#/components/schemas/ChannelCurrency"},"intake":{"type":"object","properties":{"importing":{"type":"boolean"},"notBroughtIn":{"type":"integer","minimum":0},"reportedAt":{"type":"string"}},"required":["importing","notBroughtIn","reportedAt"],"additionalProperties":false},"attention":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,47}$"},"severity":{"$ref":"#/components/schemas/AttentionSeverity"},"message":{"type":"string","minLength":1,"maxLength":200},"link":{"$ref":"#/components/schemas/ChannelSettingsPath_1"}},"required":["kind","severity","message"],"additionalProperties":false},"maxItems":20},"reportedAt":{"type":"string"}},"required":["items","reportedAt"],"additionalProperties":false},"collects":{"type":"array","items":{"$ref":"#/components/schemas/ChannelCollectionEncoded"}},"connectedAt":{"type":"string"},"disconnectedAt":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","appId","type","externalId","name","status","connectedAt","createdAt","updatedAt"],"additionalProperties":false},"ChannelListEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChannelEncoded"}}},"required":["items"],"additionalProperties":false},"ConnectChannelEncoded":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ChannelType"},"externalId":{"type":"string","minLength":1,"maxLength":255},"name":{"type":"string","minLength":1,"maxLength":120},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/ChannelPublicationEncoded"}},"orderUrl":{"$ref":"#/components/schemas/ChannelOrderUrl"},"settingsPath":{"$ref":"#/components/schemas/ChannelSettingsPath"},"currency":{"$ref":"#/components/schemas/ChannelCurrency"},"collects":{"type":"array","items":{"$ref":"#/components/schemas/ChannelCollectionEncoded"}}},"required":["type","externalId","name"],"additionalProperties":false},"ChannelConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChannelConflict"]},"channelId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","channelId","reason"],"additionalProperties":false},"ChannelNotYoursEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ChannelNotYours"]},"channelId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","channelId","reason"],"additionalProperties":false},"ReportChannelIntakeEncoded":{"type":"object","properties":{"importing":{"type":"boolean"},"notBroughtIn":{"type":"integer","minimum":0}},"required":["importing","notBroughtIn"],"additionalProperties":false},"ReportChannelAttentionEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChannelAttentionItemEncoded"},"maxItems":20}},"required":["items"],"additionalProperties":false},"SourceEncoded":{"type":"object","properties":{"sourceId":{"$ref":"#/components/schemas/SrcId"},"appId":{"$ref":"#/components/schemas/AppId"},"type":{"$ref":"#/components/schemas/SourceType"},"name":{"type":"string","minLength":1,"maxLength":120},"status":{"$ref":"#/components/schemas/SourceStatus"},"importedAt":{"type":"string"},"counts":{"type":"array","items":{"$ref":"#/components/schemas/SourceCountEncoded"}},"connectedAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["sourceId","appId","type","name","status","counts","connectedAt","updatedAt"],"additionalProperties":false},"SourceListEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SourceEncoded"}}},"required":["items"],"additionalProperties":false},"DescribeSourceEncoded":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/SourceType"},"name":{"type":"string","minLength":1,"maxLength":120},"status":{"$ref":"#/components/schemas/SourceStatus"},"counts":{"type":"array","items":{"$ref":"#/components/schemas/SourceCountEncoded"}}},"required":["type","name","status"],"additionalProperties":false},"SourceNotYoursEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SourceNotYours"]},"sourceId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","sourceId","reason"],"additionalProperties":false},"SourceAlreadyRetiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SourceAlreadyRetired"]},"sourceId":{"type":"string"}},"required":["_tag","sourceId"],"additionalProperties":false},"SourceConflictEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SourceConflict"]},"sourceId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","sourceId","reason"],"additionalProperties":false},"TransferSortKey":{"type":"string","enum":["createdAt","updatedAt","status","reference"],"description":"The column the transfers grid is ordered by"},"TransferStatus":{"type":"string","enum":["draft","in-transit","received","cancelled"],"description":"Where a transfer stands: `draft` — not yet despatched; `in-transit` — despatched, not yet received; `received` — landed at the destination; `cancelled`"},"TransferMode":{"type":"string","enum":["two-step","instant"],"description":"How a transfer moves stock: `two-step` — despatch, then receive (units sit in transit between); `instant` — one commit, no in-transit state"},"TransferLineEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0},"despatched":{"type":"integer","minimum":0},"received":{"type":"integer","minimum":0}},"required":["sku","quantity"],"additionalProperties":false},"TransferEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TrfId"},"number":{"type":"string","minLength":1},"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"status":{"$ref":"#/components/schemas/TransferStatus"},"mode":{"$ref":"#/components/schemas/TransferMode"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/TransferLineEncoded"}},"reference":{"type":"string","minLength":1},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","number","fromLocationId","toLocationId","status","lines","createdAt","updatedAt"],"additionalProperties":false},"TransferPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TransferEncoded"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","offset"],"additionalProperties":false},"TransferNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TransferNotFound"]},"transferId":{"type":"string"}},"required":["_tag","transferId"],"additionalProperties":false},"CreateTransferEncoded":{"type":"object","properties":{"fromLocationId":{"$ref":"#/components/schemas/LocId"},"toLocationId":{"$ref":"#/components/schemas/LocId"},"mode":{"$ref":"#/components/schemas/TransferMode"},"reference":{"type":"string","minLength":1},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1}},"required":["fromLocationId","toLocationId","reference","lines"],"additionalProperties":false},"TransfersDisabledEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TransfersDisabled"]}},"required":["_tag"],"additionalProperties":false},"TransferModeNotAllowedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TransferModeNotAllowed"]},"mode":{"$ref":"#/components/schemas/TransferMode"},"policy":{"$ref":"#/components/schemas/TransferPolicy"}},"required":["_tag","mode","policy"],"additionalProperties":false},"DespatchTransferEncoded":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku_1"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1},"reference":{"type":"string","minLength":1}},"required":["reference"],"additionalProperties":false},"TransferNotInStateEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TransferNotInState"]},"transferId":{"type":"string"},"status":{"$ref":"#/components/schemas/TransferStatus"},"expected":{"type":"string"}},"required":["_tag","transferId","status","expected"],"additionalProperties":false},"TransferQuantityExceededEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TransferQuantityExceeded"]},"transferId":{"type":"string"},"sku":{"type":"string"},"outstanding":{"type":"integer"},"requested":{"type":"integer"}},"required":["_tag","transferId","sku","outstanding","requested"],"additionalProperties":false},"ReceiveTransferEncoded":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku_1"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["sku","quantity"],"additionalProperties":false},"minItems":1},"reference":{"type":"string","minLength":1}},"required":["reference"],"additionalProperties":false},"CancelTransferEncoded":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"additionalProperties":false},"StocktakeStatus":{"type":"string","enum":["open","completed","cancelled"],"description":"`open` — being counted; `completed` — its counts set on-hand and its costs valued the stock; `cancelled` — abandoned, nothing it counted moved"},"StocktakeSummaryEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StkId"},"number":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/StocktakeKind"},"status":{"$ref":"#/components/schemas/StocktakeStatus"},"locationIds":{"type":"array","items":{"$ref":"#/components/schemas/LocId"}},"counted":{"type":"integer","minimum":0},"costed":{"type":"integer","minimum":0},"startedAt":{"type":"string"},"completedAt":{"type":"string"},"cancelledAt":{"type":"string"}},"required":["id","number","kind","status","locationIds","counted","costed","startedAt"],"additionalProperties":false},"StocktakeListEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StocktakeSummaryEncoded"}}},"required":["items"],"additionalProperties":false},"StocktakeCountEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"counted":{"type":"integer","minimum":0}},"required":["sku","locationId","counted"],"additionalProperties":false},"StocktakeCostEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"unitCostCents":{"type":"number","minimum":0}},"required":["sku","unitCostCents"],"additionalProperties":false},"StocktakeEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StkId"},"number":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/StocktakeKind"},"status":{"$ref":"#/components/schemas/StocktakeStatus"},"locationIds":{"type":"array","items":{"$ref":"#/components/schemas/LocId"}},"counts":{"type":"array","items":{"$ref":"#/components/schemas/StocktakeCountEncoded"}},"costs":{"type":"array","items":{"$ref":"#/components/schemas/StocktakeCostEncoded"}},"startedAt":{"type":"string"},"completedAt":{"type":"string"},"cancelledAt":{"type":"string"},"reason":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","number","kind","status","locationIds","counts","costs","startedAt","updatedAt"],"additionalProperties":false},"StocktakeNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["StocktakeNotFound"]},"stocktakeId":{"type":"string"}},"required":["_tag","stocktakeId"],"additionalProperties":false},"StocktakeSheetLineEncoded":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"name":{"type":"string"},"locationId":{"$ref":"#/components/schemas/LocId"},"expected":{"type":"integer","minimum":0},"counted":{"type":"integer","minimum":0},"unitCostCents":{"type":"number","minimum":0},"suggestedCostCents":{"type":"number","minimum":0},"missingCost":{"type":"boolean"}},"required":["sku","name","locationId","expected","missingCost"],"additionalProperties":false},"StocktakeSheetEncoded":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"kind":{"$ref":"#/components/schemas/StocktakeKind"},"status":{"$ref":"#/components/schemas/StocktakeStatus"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/StocktakeSheetLineEncoded"}},"total":{"type":"integer","minimum":0},"missingCosts":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0}},"required":["stocktakeId","kind","status","lines","total","missingCosts","limit","offset"],"additionalProperties":false},"StartStocktakeEncoded":{"type":"object","properties":{"stocktakeId":{"$ref":"#/components/schemas/StkId"},"locationIds":{"type":"array","items":{"$ref":"#/components/schemas/LocId"},"minItems":1}},"required":["stocktakeId"],"additionalProperties":false},"StocktakeInProgressEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["StocktakeInProgress"]},"stocktakeId":{"type":"string"}},"required":["_tag","stocktakeId"],"additionalProperties":false},"StocktakeLineRefusedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["StocktakeLineRefused"]},"stocktakeId":{"type":"string"},"sku":{"type":"string"},"locationId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","stocktakeId","reason"],"additionalProperties":false},"RecordStocktakeCountsEncoded":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"locationId":{"$ref":"#/components/schemas/LocId"},"counted":{"type":"integer","minimum":0}},"required":["sku","counted"],"additionalProperties":false},"maxItems":5000},"costs":{"type":"array","items":{"$ref":"#/components/schemas/StocktakeCostEncoded"},"maxItems":5000}},"additionalProperties":false},"StocktakeNotOpenEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["StocktakeNotOpen"]},"stocktakeId":{"type":"string"},"status":{"$ref":"#/components/schemas/StocktakeStatus"}},"required":["_tag","stocktakeId","status"],"additionalProperties":false},"StocktakeIncompleteEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["StocktakeIncomplete"]},"stocktakeId":{"type":"string"},"missing":{"type":"integer","minimum":0},"skus":{"type":"array","items":{"type":"string"}}},"required":["_tag","stocktakeId","missing","skus"],"additionalProperties":false},"OpeningStocktakeAtGoLiveEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["OpeningStocktakeAtGoLive"]},"stocktakeId":{"type":"string"}},"required":["_tag","stocktakeId"],"additionalProperties":false},"CancelStocktakeEncoded":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false},"CommissionGroupEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CgrId"},"name":{"type":"string","minLength":1,"maxLength":80},"baseRateBps":{"$ref":"#/components/schemas/CommissionRateBps"},"description":{"type":"string","maxLength":500},"catalogs":{"$ref":"#/components/schemas/GroupCatalogs"},"archived":{"type":"boolean"}},"required":["id","name","baseRateBps"],"additionalProperties":false},"CommissionGroupListEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CommissionGroupEncoded"}}},"required":["items"],"additionalProperties":false},"SaveCommissionGroupEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"baseRateBps":{"$ref":"#/components/schemas/CommissionRateBps"},"description":{"type":"string","maxLength":500}},"required":["name","baseRateBps"],"additionalProperties":false},"CommissionGroupNameTakenEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CommissionGroupNameTaken"]},"name":{"type":"string"}},"required":["_tag","name"],"additionalProperties":false},"CommissionGroupArchivedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CommissionGroupArchived"]},"groupId":{"type":"string"}},"required":["_tag","groupId"],"additionalProperties":false},"DefaultCommissionGroupFixedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["DefaultCommissionGroupFixed"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"SetGroupCatalogsEncoded":{"type":"object","properties":{"catalogs":{"$ref":"#/components/schemas/GroupCatalogs"}},"required":["catalogs"],"additionalProperties":false},"CommissionGroupNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CommissionGroupNotFound"]},"groupId":{"type":"string"}},"required":["_tag","groupId"],"additionalProperties":false},"CommissionGroupInUseEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CommissionGroupInUse"]},"groupId":{"type":"string"},"members":{"type":"integer"}},"required":["_tag","groupId","members"],"additionalProperties":false},"CommissionMemberEncoded":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"groupId":{"$ref":"#/components/schemas/CgrId"}},"required":["userId","groupId"],"additionalProperties":false},"CommissionMemberListEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CommissionMemberEncoded"}}},"required":["items"],"additionalProperties":false},"AssignCommissionGroupEncoded":{"type":"object","properties":{"groupId":{"$ref":"#/components/schemas/CgrId"}},"required":["groupId"],"additionalProperties":false},"CommissionSettingsEncoded":{"type":"object","properties":{"earnedOn":{"$ref":"#/components/schemas/CommissionEarnedOn"},"earner":{"$ref":"#/components/schemas/CommissionEarner"}},"required":["earnedOn"],"additionalProperties":false},"SkuCommissionRule":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"rule":{"$ref":"#/components/schemas/CommissionRule"}},"required":["sku","rule"],"additionalProperties":false},"CatalogCommissionEncoded":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SkuCommissionRule"}},"inheritsFrom":{"$ref":"#/components/schemas/CatId"}},"required":["catalogId","rules"],"additionalProperties":false},"SetCatalogCommissionEncoded":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/CommissionRule"}},"required":["rule"],"additionalProperties":false},"SalesRepSnapshot":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"groupId":{"$ref":"#/components/schemas/CgrId"},"groupName":{"type":"string","minLength":1,"maxLength":80},"baseRateBps":{"$ref":"#/components/schemas/CommissionRateBps"}},"required":["userId","groupId","groupName","baseRateBps"],"additionalProperties":false},"CommissionRule_1":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["uncommissionable"]}},"required":["_tag"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["rates"]},"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupRate"},"minItems":1,"maxItems":100}},"required":["_tag","groups"],"additionalProperties":false}]},"LineCommission":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"rule":{"$ref":"#/components/schemas/CommissionRule_1"}},"additionalProperties":false},"CatalogTerms":{"type":"object","properties":{"catalogId":{"$ref":"#/components/schemas/CatId"},"open":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","properties":{"sku":{"$ref":"#/components/schemas/Sku"},"commission":{"$ref":"#/components/schemas/LineCommission"}},"required":["sku","commission"],"additionalProperties":false}}},"required":["catalogId","open","rules"],"additionalProperties":false},"SalesTermsEncoded":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/CommissionSettingsEncoded"},"rep":{"$ref":"#/components/schemas/SalesRepSnapshot"},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/CatalogTerms"}}},"required":["settings","catalogs"],"additionalProperties":false},"JournalHead":{"type":"object","properties":{"at":{"type":"string"},"sequence":{"type":"integer","minimum":0}},"required":["at"],"additionalProperties":false,"description":"Where a tenant's journal stood at a moment."}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A tenant JWT: sign in through the auth service, choose the organization, then `GET /api/auth/token`. Tokens last 15 minutes."}}},"security":[],"tags":[{"name":"items","description":"Commands and queries over inventory items."},{"name":"locations","description":"The places this tenant holds stock."},{"name":"products","description":"The product catalog: products, their options, and the variants that carry SKUs. Sits on top of the SKU master — a variant either *is* an inventory item or is a composite of several, and its availability is always derived from inventory, never held here."},{"name":"assets","description":"Files attached to SKUs and products — photos, spec sheets, drawings. Bytes live in a private bucket and are reached only through signed, expiring URLs; the journal holds the fact of each attachment."},{"name":"catalogs","description":"Channel catalogs: which products, prices and locations each selling view is allowed to see."},{"name":"settings","description":"How this tenant is allowed to move stock, how it is taxed, and the basis its books are kept on."},{"name":"fx","description":"Central banks' published reference rates into the tenant's home currency."},{"name":"views","description":"Saved list views: named searches and filters every operator in the tenant shares."},{"name":"accounts","description":"The chart of accounts: the ledger accounts a SKU's stock, sales and cost of sales post to. Organization-level configuration, read by every account picker and edited under Settings."},{"name":"channels","description":"Sales channels: the places this tenant sells — the stores and marketplace accounts its apps provide — with the catalogs each publishes. A channel's locations are its bindings on `/locations`; its orders name it as their source."},{"name":"sources","description":"Legacy sources: the platforms this tenant is migrating from — whatever legacy platforms apps provide — each registered and kept current by its app. Evidence for the onboarding walk and the admin; what a retired app may still do is its installation's, in auth-service."},{"name":"transfers","description":"Moving stock between the tenant's own locations."},{"name":"stocktakes","description":"Counting the tenant's stock; the first completed count opens the general ledger."},{"name":"commissions","description":"Sales commissions: groups and their base rates and catalogs, who is in which, when commission is earned and by whom, and each catalog's rules per SKU."},{"name":"events","description":"The append-only event log: replay for catch-up, SSE for real-time."}],"servers":[{"url":"https://inventory.getmanifold.io","description":"Production"}]}