{ "openapi": "3.1.0", "info": { "title": "Floormode REST API", "version": "0.1.0", "summary": "The external REST surface of the Floormode WMS + OMS, generated from its registry.", "description": "The external REST API of Floormode — a WMS + OMS for e-commerce.\n\nEvery endpoint below is generated from the operations registry\n(`src/shared/operations.ts`), which is the single source of truth behind both\nthis API and the MCP server. An operation's **operation id** (`orders_list`)\nnames the same operation on all three surfaces, so what you learn here transfers\nto an agent calling MCP code mode, where the first `_` becomes a dot:\n`app.orders.list({…})`.\n\n## Authentication\n\nSend `Authorization: Bearer `. Two token types are accepted:\n\n- a **WorkOS OAuth access token** — this is the external/agent path; discovery\n metadata lives at `/.well-known/oauth-protected-resource` (RFC 9728);\n- a **Shopify session token**, when the caller is the embedded app.\n\nThe app's own browser session cookie is also accepted, but that path exists for\nthe standalone SPA, not for integrations. A request with no usable identity is\nanswered `401`.\n\n## Plans\n\nThe external API requires the **Enterprise** plan. A caller below that tier is\nanswered `403` with `{\"code\": \"plan_required\", \"requiredPlan\": \"enterprise\"}`\n— a plan refusal is an authorization refusal, so it shares the one `403`\nstatus with every other `forbidden` answer and is distinguished by its\n`code`. Individual operations may additionally declare a minimum plan; that is\npublished per operation as `x-min-plan` and repeated in the operation's\ndescription.\n\n## Request shape\n\n- `GET` and `DELETE` take their input from the **query string**. Values are\n coerced against each parameter's declared type before validation, so\n `?limit=25` reaches a numeric field as the number `25`. Arrays accept a\n repeated parameter (`?ids=a&ids=b`) or a JSON array; objects accept JSON.\n- A query parameter the operation does not declare is **refused**, not ignored:\n `400` with `{\"code\": \"unknown_parameter\", \"unknown\": […], \"accepted\": […]}`.\n A misspelled filter therefore fails loudly instead of returning an unfiltered\n list that looks correct.\n- `POST`, `PUT` and `PATCH` take a **JSON body**. Unknown body keys are\n ignored, so a caller's own envelope fields are harmless.\n\n## Response shape\n\nA success is always `{\"data\": …}`. Because the operation's return contract is\ndeclared on the handler rather than in the published registry, `data` is\ndescribed permissively here; each operation's description says what it returns.\n\nAn error is always `{\"error\": \"\"}`, plus `\"code\"` whenever the\nfailure is a domain refusal the object classified. Those codes map to HTTP\nstatuses like this:\n\n| Code | HTTP status |\n| --- | --- |\n| `conflict` | 409 |\n| `forbidden` | 403 |\n| `internal` | 500 |\n| `invalid_input` | 400 |\n| `invalid_output` | 500 |\n| `not_found` | 404 |\n| `organization_changed` | 409 |\n| `payload_too_large` | 413 |\n| `unauthorized` | 401 |\n| `unknown_function` | 404 |\n\n`GET /api/v1` returns the machine-readable catalog of every operation with its\ninput JSON Schema — the same information as this document, served live by the\nAPI itself. It takes the same bearer credential as every operation (`401`\nwithout one), but needs no plan." }, "servers": [ { "url": "https://{host}", "description": "The Cloudflare Worker your Floormode app is deployed on. Replace `host` with your own app domain — every tenant is addressed by the caller's identity, never by the URL.", "variables": { "host": { "default": "app.example.com", "description": "Your Floormode app's domain." } } } ], "tags": [ { "name": "accounting", "description": "2 operations under `/api/v1/accounting`." }, { "name": "alerts", "description": "1 operations under `/api/v1/alerts`." }, { "name": "analytics", "description": "8 operations under `/api/v1/analytics`." }, { "name": "billing", "description": "2 operations under `/api/v1/billing`." }, { "name": "bins", "description": "7 operations under `/api/v1/bins`." }, { "name": "boxes", "description": "4 operations under `/api/v1/boxes`." }, { "name": "carriers", "description": "5 operations under `/api/v1/carriers`." }, { "name": "cartonization", "description": "1 operations under `/api/v1/cartonization`." }, { "name": "catalog", "description": "Runtime discovery of the API itself." }, { "name": "catalog", "description": "Runtime discovery of the API itself." }, { "name": "checkout-options", "description": "2 operations under `/api/v1/checkout-options`." }, { "name": "connections", "description": "1 operations under `/api/v1/connections`." }, { "name": "costing", "description": "4 operations under `/api/v1/costing`." }, { "name": "counts", "description": "11 operations under `/api/v1/counts`." }, { "name": "customer-pages", "description": "2 operations under `/api/v1/customer-pages`." }, { "name": "dashboard", "description": "5 operations under `/api/v1/dashboard`." }, { "name": "disposition", "description": "3 operations under `/api/v1/disposition`." }, { "name": "domains", "description": "4 operations under `/api/v1/domains`." }, { "name": "entity-events", "description": "1 operations under `/api/v1/entity-events`." }, { "name": "exceptions", "description": "2 operations under `/api/v1/exceptions`." }, { "name": "forecast", "description": "4 operations under `/api/v1/forecast`." }, { "name": "freight", "description": "3 operations under `/api/v1/freight`." }, { "name": "history", "description": "8 operations under `/api/v1/history`." }, { "name": "holds", "description": "5 operations under `/api/v1/holds`." }, { "name": "integrations", "description": "3 operations under `/api/v1/integrations`." }, { "name": "inventory", "description": "28 operations under `/api/v1/inventory`." }, { "name": "jobs", "description": "2 operations under `/api/v1/jobs`." }, { "name": "label-printer-profiles", "description": "4 operations under `/api/v1/label-printer-profiles`." }, { "name": "label-templates", "description": "5 operations under `/api/v1/label-templates`." }, { "name": "labour", "description": "7 operations under `/api/v1/labour`." }, { "name": "local-items", "description": "4 operations under `/api/v1/local-items`." }, { "name": "local-stock", "description": "2 operations under `/api/v1/local-stock`." }, { "name": "location-types", "description": "2 operations under `/api/v1/location-types`." }, { "name": "locations", "description": "15 operations under `/api/v1/locations`." }, { "name": "lots", "description": "11 operations under `/api/v1/lots`." }, { "name": "manifests", "description": "2 operations under `/api/v1/manifests`." }, { "name": "notes", "description": "2 operations under `/api/v1/notes`." }, { "name": "notifications", "description": "7 operations under `/api/v1/notifications`." }, { "name": "orders", "description": "35 operations under `/api/v1/orders`." }, { "name": "pack-instructions", "description": "3 operations under `/api/v1/pack-instructions`." }, { "name": "packing", "description": "25 operations under `/api/v1/packing`." }, { "name": "people", "description": "21 operations under `/api/v1/people`." }, { "name": "picking", "description": "23 operations under `/api/v1/picking`." }, { "name": "pickups", "description": "2 operations under `/api/v1/pickups`." }, { "name": "print-jobs", "description": "2 operations under `/api/v1/print-jobs`." }, { "name": "printers", "description": "1 operations under `/api/v1/printers`." }, { "name": "privacy", "description": "4 operations under `/api/v1/privacy`." }, { "name": "production", "description": "1 operations under `/api/v1/production`." }, { "name": "products", "description": "3 operations under `/api/v1/products`." }, { "name": "receiving", "description": "20 operations under `/api/v1/receiving`." }, { "name": "replenishment", "description": "2 operations under `/api/v1/replenishment`." }, { "name": "return-requests", "description": "11 operations under `/api/v1/return-requests`." }, { "name": "returns", "description": "18 operations under `/api/v1/returns`." }, { "name": "roles", "description": "4 operations under `/api/v1/roles`." }, { "name": "routing", "description": "13 operations under `/api/v1/routing`." }, { "name": "rules", "description": "7 operations under `/api/v1/rules`." }, { "name": "saved-views", "description": "6 operations under `/api/v1/saved-views`." }, { "name": "scan", "description": "1 operations under `/api/v1/scan`." }, { "name": "search", "description": "1 operations under `/api/v1/search`." }, { "name": "serials", "description": "6 operations under `/api/v1/serials`." }, { "name": "settings", "description": "7 operations under `/api/v1/settings`." }, { "name": "setup", "description": "1 operations under `/api/v1/setup`." }, { "name": "shipments", "description": "9 operations under `/api/v1/shipments`." }, { "name": "shipping-rules", "description": "5 operations under `/api/v1/shipping-rules`." }, { "name": "shopify-locations", "description": "1 operations under `/api/v1/shopify-locations`." }, { "name": "sku-slotting", "description": "4 operations under `/api/v1/sku-slotting`." }, { "name": "slotting", "description": "9 operations under `/api/v1/slotting`." }, { "name": "stations", "description": "8 operations under `/api/v1/stations`." }, { "name": "stores", "description": "8 operations under `/api/v1/stores`." }, { "name": "sync", "description": "8 operations under `/api/v1/sync`." }, { "name": "tasks", "description": "15 operations under `/api/v1/tasks`." }, { "name": "tenant", "description": "1 operations under `/api/v1/tenant`." }, { "name": "trackers", "description": "1 operations under `/api/v1/trackers`." }, { "name": "tracking-brand", "description": "1 operations under `/api/v1/tracking-brand`." }, { "name": "user-prefs", "description": "4 operations under `/api/v1/user-prefs`." }, { "name": "values", "description": "1 operations under `/api/v1/values`." }, { "name": "variants", "description": "17 operations under `/api/v1/variants`." }, { "name": "warehouse-transfers", "description": "15 operations under `/api/v1/warehouse-transfers`." }, { "name": "warehouses", "description": "14 operations under `/api/v1/warehouses`." }, { "name": "waves", "description": "9 operations under `/api/v1/waves`." }, { "name": "webhooks", "description": "8 operations under `/api/v1/webhooks`." }, { "name": "work", "description": "2 operations under `/api/v1/work`." }, { "name": "worker-profiles", "description": "4 operations under `/api/v1/worker-profiles`." }, { "name": "zones", "description": "6 operations under `/api/v1/zones`." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1": { "get": { "operationId": "operations_catalog", "summary": "List every operation this API exposes, with its input JSON Schema.", "description": "The self-describing catalog. Returns the same operations this document describes, straight from the running registry — a client that wants to discover the surface at runtime reads this instead of shipping a copy of the spec. Bearer-gated like every operation below it (audit S-14), but needs no plan.", "tags": [ "catalog" ], "responses": { "200": { "description": "The operations catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsCatalog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/accounting/export": { "get": { "operationId": "accounting_export", "summary": "accounting_export", "description": "A month's accounting figures for the accountant, read from the history archive's books: the cost of goods sold and the stock value at the month's end and start, per currency (cents), the journal lines the chosen booking method posts (debit and credit account, per warehouse when the setup splits), the shipments without a cost, the month's state (ready, waiting for its books, open, first, empty, no_costs, books_required, setup) and the files: download them from GET /api/accounting/export/{YYYY-MM}?format=datev|xero|csv. The month is a calendar month in the store's first warehouse's time zone; without one, the month that closed last (currentMonth names the open one).\n\n**Operation id:** `accounting_export` — the same operation is `app.accounting.export({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/accounting_export`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "accounting" ], "x-operation-kind": "query", "parameters": [ { "name": "month", "in": "query", "required": false, "description": "The month, `YYYY-MM`, on the calendar of the store's first warehouse. Absent: the month that closed last.", "schema": { "description": "The month, `YYYY-MM`, on the calendar of the store's first warehouse. Absent: the month that closed last.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "format", "in": "query", "required": false, "description": "Which file `files` names first; the figures are the same.", "schema": { "description": "Which file `files` names first; the figures are the same.", "type": "string", "enum": [ "datev", "xero", "csv" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/accounting/settings": { "post": { "operationId": "accounting_settings_set", "summary": "accounting_settings_set", "description": "Save how the accounting export books a month, once for the store: the chart of accounts (skr03, skr04, xero or custom), whether purchases are booked as expense (the month posts the change of the stock value) or to stock (it posts the cost of goods sold), the accounts (digits of the DATEV account length for SKR and custom, up to 10 letters or digits for Xero), whether lines are split by warehouse, and the DATEV and Xero details. Saving what is stored changes nothing.\n\n**Operation id:** `accounting_settings_set` — the same operation is `app.accounting.settings_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/accounting_settings_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "accounting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "chart": { "type": "string", "enum": [ "skr03", "skr04", "xero", "custom" ] }, "purchasesAre": { "type": "string", "enum": [ "expense", "stock" ] }, "accounts": { "type": "object", "properties": { "stock": { "type": "string", "maxLength": 10 }, "stockChange": { "type": "string", "maxLength": 10 }, "cogs": { "type": "string", "maxLength": 10 } }, "required": [ "stock", "stockChange", "cogs" ] }, "splitByWarehouse": { "type": "boolean" }, "datev": { "type": "object", "properties": { "consultantNumber": { "type": "string", "pattern": "^(\\d{4,7})?$" }, "clientNumber": { "type": "string", "pattern": "^(\\d{1,5})?$" }, "accountLength": { "type": "integer", "minimum": 4, "maximum": 8 }, "fiscalYearStartMonth": { "type": "integer", "minimum": 1, "maximum": 12 } }, "required": [ "consultantNumber", "clientNumber", "accountLength", "fiscalYearStartMonth" ] }, "xero": { "type": "object", "properties": { "region": { "type": "string", "enum": [ "uk", "au", "nz", "us" ] }, "taxRate": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "region", "taxRate" ] } }, "required": [ "v", "chart", "purchasesAre", "accounts", "splitByWarehouse", "datev", "xero" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/alerts": { "get": { "operationId": "alerts_list", "summary": "alerts_list", "description": "The tenant's operational alert timeline: SLA breaches, sync-failure spikes, count variances, near-expiry lots, inventory writer gaps, peer outages. Each row carries the alert `type`, `severity` (info, warning, critical), `message`, the `entityRef` it is about (`ffd::`) and who raised it. Recorded whether or not Alertified is connected — forwarding is what the connection gates. Filter by a set of severities, one `type` (a closed vocabulary; the input schema lists every member), an instant (`atFromMs`) or `notSent`; sort newest first (default) or oldest first; a disclosed page (`rows`/`capped`/`cursor`, max 50): pass the answered `cursor` back. Cursors issued before 2026-10-06 are refused; restart from page one.\n\n**Operation id:** `alerts_list` — the same operation is `app.alerts.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/alerts_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "alerts" ], "x-operation-kind": "query", "parameters": [ { "name": "severities", "in": "query", "required": false, "description": "Any of these severities; absent = every severity. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these severities; absent = every severity.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "info", "warning", "critical" ] } } }, { "name": "type", "in": "query", "required": false, "description": "One alert type, e.g. sla_breach (the catalog lists them all); absent = every type.", "schema": { "description": "One alert type, e.g. sla_breach (the catalog lists them all); absent = every type.", "type": "string", "enum": [ "automation_rule", "backorder", "backorder_restocked", "barcode_aliases_refused", "checkout_options_cap_reached", "count_variance", "external_fulfillment_unbooked", "fo_close_deferred", "handback_overdue", "integration_key_reuse", "inventory_writer_drift", "inventory_writer_drift_cleared", "inventory_writer_gap", "landed_cost_refused", "local_snapshot_skipped", "lot_blocked", "lot_expiry_tightened", "near_expiry", "order_action_attention", "order_edit_mirror_refresh_dead", "order_refresh_dead", "oversell_risk", "pack_ship_skipped", "payment_auth_window", "peer_capability_revoked", "peer_reachable", "peer_unreachable", "pick_lines_dropped", "pick_release_skipped", "po_push_confirmation_overflow", "receipt_price_deviation", "refund_failure", "refund_stock_unbooked", "reorder_suggested", "return_label_unprintable", "rule_matched_noop", "shipment_weight_estimated", "sibling_report_refused", "sla_breach", "source_lines_exceeded", "stock_release_clamped", "sync_failure", "token_refresh_refused", "token_refresh_unresolved", "transfer_source_effect_refused", "wave_auto_release_refused" ] } }, { "name": "atFromMs", "in": "query", "required": false, "description": "Alerts at or after this instant (milliseconds since 1970, UTC).", "schema": { "description": "Alerts at or after this instant (milliseconds since 1970, UTC).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "state", "in": "query", "required": false, "description": "`open` (the default: alerts whose condition still holds) or `all` (resolved ones too).", "schema": { "description": "`open` (the default: alerts whose condition still holds) or `all` (resolved ones too).", "type": "string", "enum": [ "open", "all" ] } }, { "name": "notSent", "in": "query", "required": false, "description": "Only alerts that could not be forwarded. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only alerts that could not be forwarded.", "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "schema": { "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "type": "string", "enum": [ "at:desc", "at:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Alerts per page (max 50).", "schema": { "description": "Alerts per page (max 50).", "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/adjustments-by-reason": { "get": { "operationId": "analytics_adjustments_by_reason", "summary": "analytics_adjustments_by_reason", "description": "Stock adjustments grouped by reason code in the window: unsigned units, signed net and movement counts from the adjust ledger. Bounded scan.\n\n**Operation id:** `analytics_adjustments_by_reason` — the same operation is `app.analytics.adjustments_by_reason({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_adjustments_by_reason`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/fulfillment-times": { "get": { "operationId": "analytics_fulfillment_times", "summary": "analytics_fulfillment_times", "description": "The team's fulfillment times per day over each warehouse's last `days` calendar days (1 = today, at most a year) or its month or year to date (`toDate`; exactly one of the two), in one warehouse or every one, each warehouse on its own calendar (its time zone, else UTC): customer pick batches completed and the units they picked, parcels completed, the typical (median) pick time per batch and pack time per parcel, and units picked per hour of walking (over timed batches only), plus the same figures for the whole window. Team totals only, never a figure per person: a time or rate taken over fewer than two people is withheld (null, with `pickWithheld` or `packWithheld`), per day and for the window; the other kind's figure stays. Counts are exact; a typical time is the middle of the median's duration bucket (eight to each doubling), within about 4 %. Read as one row a day and warehouse; parcels completed are the one count of parcels packed (dashboard_output and packing_time_summary count today the same).\n\n**Operation id:** `analytics_fulfillment_times` — the same operation is `app.analytics.fulfillment_times({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_fulfillment_times`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many of each warehouse's own calendar days, ending with its today: 1 = today, 7 = today and the six days before it. At most a year.", "schema": { "description": "How many of each warehouse's own calendar days, ending with its today: 1 = today, 7 = today and the six days before it. At most a year.", "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "toDate", "in": "query", "required": false, "description": "Each warehouse's month or year so far, by its own calendar, its today included.", "schema": { "description": "Each warehouse's month or year so far, by its own calendar, its today included.", "type": "string", "enum": [ "month", "year" ] } }, { "name": "warehouseId", "in": "query", "required": false, "description": "One warehouse; absent or null = every warehouse.", "schema": { "description": "One warehouse; absent or null = every warehouse.", "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/inventory-value": { "get": { "operationId": "analytics_inventory_value", "summary": "analytics_inventory_value", "description": "Current inventory value: Σ on-hand across bins × variant unit price (a point-in-time snapshot, no date range). Unit cost is not mirrored from Shopify, so the basis is the selling price (reported via `basis`).\n\n**Operation id:** `analytics_inventory_value` — the same operation is `app.analytics.inventory_value({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_inventory_value`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/on-time-ship": { "get": { "operationId": "analytics_on_time_ship", "summary": "analytics_on_time_ship", "description": "On-time-ship percentage for shipments in the window (shipped on or before the fulfillment order's fulfillBy). Only shipments whose order has a due date are counted; `unmeasured` is the number shipped without one.\n\n**Operation id:** `analytics_on_time_ship` — the same operation is `app.analytics.on_time_ship({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_on_time_ship`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/order-cycle-time": { "get": { "operationId": "analytics_order_cycle_time", "summary": "analytics_order_cycle_time", "description": "Order cycle time in hours (created → first shipment) for orders shipped in the window: count, average, median, p90 and a per-day average series.\n\n**Operation id:** `analytics_order_cycle_time` — the same operation is `app.analytics.order_cycle_time({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_order_cycle_time`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/pick-accuracy": { "get": { "operationId": "analytics_pick_accuracy", "summary": "analytics_pick_accuracy", "description": "Pick accuracy in the window: picked / (picked + short) lines from the event stream, plus a per-day picked/short series. Bounded scan with disclosure.\n\n**Operation id:** `analytics_pick_accuracy` — the same operation is `app.analytics.pick_accuracy({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_pick_accuracy`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/return-rate-by-reason": { "get": { "operationId": "analytics_return_rate_by_reason", "summary": "analytics_return_rate_by_reason", "description": "Returned units grouped by reason code, from return ledger movements in the window. Bounded scan with capped/scannedThrough disclosure.\n\n**Operation id:** `analytics_return_rate_by_reason` — the same operation is `app.analytics.return_rate_by_reason({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_return_rate_by_reason`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/analytics/throughput": { "get": { "operationId": "analytics_throughput", "summary": "analytics_throughput", "description": "Items picked per UTC day in a time window — the units each pick booked, a material counted in a working unit once — as team totals (never per person); parcels packed are analytics_fulfillment_times'. Bounded event scan; the response discloses capped/scannedThrough so callers know how far back the numbers reach.\n\n**Operation id:** `analytics_throughput` — the same operation is `app.analytics.throughput({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/analytics_throughput`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "analytics" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/billing": { "get": { "operationId": "billing_current", "summary": "billing_current", "description": "The tenant's subscription plan (none/essential/elevate/enhanced/enterprise), its status (active/cancelled), the managed-pricing plan name, the current period end and `effectivePlan` — the plan that actually grants features (only an active subscription counts; a cancelled one degrades to none).\n\n**Operation id:** `billing_current` — the same operation is `app.billing.current({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/billing_current`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "billing" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/billing/usage": { "get": { "operationId": "billing_usage", "summary": "billing_usage", "description": "The current billing period's order volume against the plan's allowance: the period bounds (epoch ms), `ordersInPeriod`, the effective plan's `limit` (null = no enforced allowance), `overLimit` and the cheapest `recommendedPlan` whose allowance covers the volume. Counts first operational release once per order. Exceeding grants grace through the confirmed cycle end; only new admissions then require a sufficient confirmed plan. No usage fees. Unknown cycle bounds are null; existing work always continues.\n\n**Operation id:** `billing_usage` — the same operation is `app.billing.usage({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/billing_usage`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "billing" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins": { "get": { "operationId": "bins_list", "summary": "bins_list", "description": "One warehouse's bins, a disclosed page at a time (`rows`/`capped`/`cursor`, max 200): by code (`code:asc`, the default) or along the pick route (`route:asc`). Every filter is a server predicate: a case-insensitive code prefix or a whole barcode (`search`), `zoneId`, a set of `binTypes`, `level` (`bins` = the stock-holding leaves, the default; `all` = every layout level), `state` (`active` by default, `archived`, `all`), `occupancy`, `sellable`, `pickable`, `flagged`, or an exact `code`. Pass the answered `cursor` back; a cursor from other filters, another warehouse or a renumbered route is refused as `stale_cursor`. Breaking since 2026-10-06: `warehouseId` is required; `search` matches a code prefix or a whole barcode (no longer a substring); the former zone-code, include-archived and single-type arguments are refused.\n\n**Operation id:** `bins_list` — the same operation is `app.bins.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "The warehouse whose bins are listed (required).", "schema": { "type": "string", "description": "The warehouse whose bins are listed (required).", "format": "floormode-id" } }, { "name": "search", "in": "query", "required": false, "description": "A code prefix (case-insensitive) or a whole barcode.", "schema": { "description": "A code prefix (case-insensitive) or a whole barcode.", "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "zoneId", "in": "query", "required": false, "description": "Only bins in this zone.", "schema": { "description": "Only bins in this zone.", "type": "string", "format": "floormode-id" } }, { "name": "binTypes", "in": "query", "required": false, "description": "Any of these bin types; absent (or every type) = every type. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these bin types; absent (or every type) = every type.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] } } }, { "name": "level", "in": "query", "required": false, "description": "`bins` (stock-holding leaves, the default) or `all` levels of the layout tree.", "schema": { "description": "`bins` (stock-holding leaves, the default) or `all` levels of the layout tree.", "type": "string", "enum": [ "bins", "all" ] } }, { "name": "state", "in": "query", "required": false, "description": "`active` (the default), `archived` or `all`.", "schema": { "description": "`active` (the default), `archived` or `all`.", "type": "string", "enum": [ "active", "archived", "all" ] } }, { "name": "occupancy", "in": "query", "required": false, "description": "`empty` (nothing booked in the bin) or `occupied`.", "schema": { "description": "`empty` (nothing booked in the bin) or `occupied`.", "type": "string", "enum": [ "empty", "occupied" ] } }, { "name": "sellable", "in": "query", "required": false, "description": "Only sellable (true) or non-sellable (false) bins. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only sellable (true) or non-sellable (false) bins.", "type": "boolean" } }, { "name": "pickable", "in": "query", "required": false, "description": "Only pickable (true) or non-pickable (false) bins. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only pickable (true) or non-pickable (false) bins.", "type": "boolean" } }, { "name": "flagged", "in": "query", "required": false, "description": "Only bins with (true) or without (false) a problem flag. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only bins with (true) or without (false) a problem flag.", "type": "boolean" } }, { "name": "code", "in": "query", "required": false, "description": "Exact bin code, case-insensitive: the one-row lookup a deep link needs.", "schema": { "description": "Exact bin code, case-insensitive: the one-row lookup a deep link needs.", "type": "string", "minLength": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "`code:asc` (by code, the default), `code:desc` (by code, Z to A), `route:asc` (along the pick route) or `route:desc` (the pick route from its last bin).", "schema": { "description": "`code:asc` (by code, the default), `code:desc` (by code, Z to A), `route:asc` (along the pick route) or `route:desc` (the pick route from its last bin).", "type": "string", "enum": [ "code:asc", "code:desc", "route:asc", "route:desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Bins per page (max 200).", "schema": { "description": "Bins per page (max 200).", "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "bins_create", "summary": "bins_create", "description": "Create one bin. The code is uppercased and must be unique inside the warehouse; barcode defaults to the code and pick sequence to the end of the warehouse.\n\n**Operation id:** `bins_create` — the same operation is `app.bins.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "code": { "type": "string", "minLength": 1 }, "barcode": { "type": "string" }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "binType": { "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] }, "pickable": { "type": "boolean" }, "sellable": { "type": "boolean" }, "shopifyInventoryState": { "anyOf": [ { "type": "string", "enum": [ "available", "damaged", "reserved", "quality_control", "safety_stock" ] }, { "type": "null" } ] } }, "required": [ "warehouseId", "code", "binType" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins/archive": { "post": { "operationId": "bins_archive", "summary": "bins_archive", "description": "Archive a bin. Rejected while the bin still holds stock or reservations.\n\n**Operation id:** `bins_archive` — the same operation is `app.bins.archive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_archive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "binId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins/by-ids": { "post": { "operationId": "bins_by_ids", "summary": "bins_by_ids", "description": "Resolve up to 200 bins by document id to their label data (code, barcode, zone, bin type, warehouse name). Unknown or foreign ids are skipped. Batch hydration for label printing and scan follow-ups.\n\n**Operation id:** `bins_by_ids` — the same operation is `app.bins.by_ids({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_by_ids`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "document ids of the bins." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins/get": { "get": { "operationId": "bins_get", "summary": "bins_get", "description": "Get one bin with its warehouse and current contents (max 100 stock rows).\n\n**Operation id:** `bins_get` — the same operation is `app.bins.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "query", "parameters": [ { "name": "binId", "in": "query", "required": true, "description": "document id of the bin.", "schema": { "type": "string", "description": "document id of the bin.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins/picker": { "get": { "operationId": "bins_picker_search", "summary": "bins_picker_search", "description": "Find bins of one warehouse as the bin field does: a case-insensitive code prefix in code order (max 50 per page, keyset cursor). `exact` is the one location whose code or barcode equals the text (null, with `ambiguous` true, when two differ); `destination` keeps only bins that may receive it in the rows: stock = active leaf bins, restock = sellable ones, quarantine = quarantine bins not for sale.\n\n**Operation id:** `bins_picker_search` — the same operation is `app.bins.picker_search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_picker_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "destination", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "stock", "restock", "quarantine" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bins/update": { "post": { "operationId": "bins_update", "summary": "bins_update", "description": "Update bin master data. `problemFlag: {reason}` raises a problem flag (actor and timestamp are stamped), null clears it. SIDE EFFECT: changing `sellable` queues a Shopify availability push for every variant stocked in the bin (bounded at 500 distinct variants per call) — those units enter or leave what the shop may offer without moving.\n\n**Operation id:** `bins_update` — the same operation is `app.bins.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/bins_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "bins" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "code": { "type": "string", "minLength": 1 }, "barcode": { "type": "string", "minLength": 1 }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "binType": { "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] }, "pickable": { "type": "boolean" }, "sellable": { "type": "boolean" }, "shopifyInventoryState": { "anyOf": [ { "type": "string", "enum": [ "available", "damaged", "reserved", "quality_control", "safety_stock" ] }, { "type": "null" } ] }, "problemFlag": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] }, { "type": "null" } ] } }, "required": [ "binId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/boxes": { "get": { "operationId": "boxes_list", "summary": "boxes_list", "description": "List the pack station's boxes in name-ordered pages of 100 (pass the answer's `cursor` for the next page); deleted boxes are hidden unless includeDeleted is set.\n\n**Operation id:** `boxes_list` — the same operation is `app.boxes.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/boxes_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "boxes" ], "x-operation-kind": "query", "parameters": [ { "name": "includeDeleted", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "boxes_create", "summary": "boxes_create", "description": "Create a box with its inner dimensions in millimetres.\n\n**Operation id:** `boxes_create` — the same operation is `app.boxes.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/boxes_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "boxes" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "lengthMm": { "type": "number", "exclusiveMinimum": 0 }, "widthMm": { "type": "number", "exclusiveMinimum": 0 }, "heightMm": { "type": "number", "exclusiveMinimum": 0 }, "emptyWeightGrams": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxWeightGrams": { "description": "Weight the box may carry, in grams; the cartonization split cap.", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costCents": { "description": "Box cost in cents.", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "name", "lengthMm", "widthMm", "heightMm" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/boxes/delete": { "post": { "operationId": "boxes_delete", "summary": "boxes_delete", "description": "Soft-delete a box; pack jobs packed in it keep their reference.\n\n**Operation id:** `boxes_delete` — the same operation is `app.boxes.delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/boxes_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "boxes" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "boxId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "boxId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/boxes/update": { "post": { "operationId": "boxes_update", "summary": "boxes_update", "description": "Update name, dimensions, weights or cost of a box.\n\n**Operation id:** `boxes_update` — the same operation is `app.boxes.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/boxes_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "boxes" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "boxId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1 }, "lengthMm": { "type": "number", "exclusiveMinimum": 0 }, "widthMm": { "type": "number", "exclusiveMinimum": 0 }, "heightMm": { "type": "number", "exclusiveMinimum": 0 }, "emptyWeightGrams": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxWeightGrams": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costCents": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "boxId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/carriers": { "get": { "operationId": "carriers_list", "summary": "carriers_list", "description": "List the tenant's carrier accounts (max 100): provider, label, mode, capabilities, contract handle, status and BYOC flag. The encrypted credentials are never returned — only the Worker decrypts them. Filter by one or more statuses (active, needs_reauth, disabled); a store connects at most 50 accounts that are not disabled, so a filter within active and needs_reauth answers the whole set.\n\n**Operation id:** `carriers_list` — the same operation is `app.carriers.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/carriers_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "carriers" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "active", "needs_reauth", "disabled" ] } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/carriers/get": { "get": { "operationId": "carriers_get", "summary": "carriers_get", "description": "Get one connected carrier account by id, credential-free (provider, label, mode, capabilities, contract handle, status, BYOC flag); null for an unknown id. The encrypted credentials are never returned.\n\n**Operation id:** `carriers_get` — the same operation is `app.carriers.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/carriers_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "carriers" ], "x-operation-kind": "query", "parameters": [ { "name": "carrierAccountId", "in": "query", "required": true, "description": "document id of the carrier account.", "schema": { "type": "string", "description": "document id of the carrier account.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/carriers/options": { "post": { "operationId": "carriers_set_options", "summary": "carriers_set_options", "description": "Set a carrier account's options. `encloseReturnLabel`: put a DHL return label in every domestic parcel of this DHL account, printed beside its shipping label; refused (`option_unavailable`) unless the account's DHL contract holds a DHL RETOURE billing number (procedure 07). `dangerousGoodsAgreement`: the merchant's contract covers dangerous goods, so the classes this carrier carries under an agreement (lithium batteries in, with or without a device and limited quantities for Sendcloud, EasyPost, ShipEngine and DHL Paket, the last within Germany) may be labelled; refused (`option_unavailable`) for a carrier that carries none that way. An option left out keeps its value.\n\n**Operation id:** `carriers_set_options` — the same operation is `app.carriers.set_options({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/carriers_set_options`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "carriers" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrierAccountId": { "type": "string", "description": "document id of the carrier account.", "format": "floormode-id" }, "encloseReturnLabel": { "type": "boolean" }, "dangerousGoodsAgreement": { "type": "boolean" } }, "required": [ "carrierAccountId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/carriers/sample-label": { "post": { "operationId": "carriers_sample_label", "summary": "carriers_sample_label", "description": "Ask for a sample label on one carrier account: a 1 kg parcel from a warehouse to its own address on the account's first service, with no pack job and no shipment. It shows whether the contract holds the product before the first real order. Allowed only where it costs nothing: sandbox credentials, or a live account of a carrier that does not bill unscanned labels; otherwise refused with `code: sample_label_not_allowed`. The label is made in the background; carriers.get answers it as `lastSampleLabel` (`pending`, then `created` with the label's `documentId` and tracking number, `refused` with the carrier's words, or `unanswered`). One request at a time per account (`sample_label_pending`); `warehouseId` names the warehouse, else the first active one with a complete address (`sample_label_no_address` when none has one).\n\n**Operation id:** `carriers_sample_label` — the same operation is `app.carriers.sample_label({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/carriers_sample_label`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "carriers" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrierAccountId": { "type": "string", "description": "document id of the carrier account.", "format": "floormode-id" }, "warehouseId": { "description": "document id of the warehouse to send from and to; optional.", "type": "string", "format": "floormode-id" } }, "required": [ "carrierAccountId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/carriers/services": { "get": { "operationId": "carriers_services_list", "summary": "carriers_services_list", "description": "List the carrier services a checkout option can ship with, per parcel carrier account that is active or needs its credentials renewed (needs_reauth), max 100, in label order. Each account lists its services by `serviceCode` — the exact, connection-scoped code its rates carry, the pair checkout_options_set_target takes — and label: the adapter's fixed list for UPS, DHL Parcel DE and Hermes (`catalogue: static`), otherwise the services the account's rate answers named (`catalogue: observed`, empty until the account's first rates). Disconnected and freight accounts are not listed.\n\n**Operation id:** `carriers_services_list` — the same operation is `app.carriers.services_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/carriers_services_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "carriers" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/cartonization/recommend": { "get": { "operationId": "cartonization_recommend", "summary": "cartonization_recommend", "description": "Recommend one or more boxes for a shipment, pack job or an explicit item list against the active box catalog (OMS-079). Returns a packing plan: which goods go in which box, per-box dims/weight and wasted volume, plus any items with no recorded dimensions. Pass exactly one of shipmentId, packJobId or items.\n\n**Operation id:** `cartonization_recommend` — the same operation is `app.cartonization.recommend({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/cartonization_recommend`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "cartonization" ], "x-operation-kind": "query", "parameters": [ { "name": "shipmentId", "in": "query", "required": false, "description": "Cartonize this shipment's order lines.", "schema": { "description": "Cartonize this shipment's order lines.", "type": "string", "format": "floormode-id" } }, { "name": "packJobId", "in": "query", "required": false, "description": "Cartonize this pack job's order lines.", "schema": { "description": "Cartonize this pack job's order lines.", "type": "string", "format": "floormode-id" } }, { "name": "items", "in": "query", "required": false, "description": "Cartonize an explicit item list with dims supplied directly. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Cartonize an explicit item list with dims supplied directly.", "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "lengthMm": { "type": "number", "exclusiveMinimum": 0 }, "widthMm": { "type": "number", "exclusiveMinimum": 0 }, "heightMm": { "type": "number", "exclusiveMinimum": 0 }, "weightGrams": { "type": "number", "minimum": 0 } }, "required": [ "quantity", "lengthMm", "widthMm", "heightMm", "weightGrams" ] } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/catalog/picker": { "get": { "operationId": "catalog_picker_search", "summary": "catalog_picker_search", "description": "Browse the catalog as the product picker does: products in title order (max 50 per page, keyset cursor), each with up to 25 live variants (variantsCapped says more exist) and the physical on-hand per variant over every warehouse or one. Scope all | title | sku (sku also matches primary and alternate barcodes exactly); vendor matches case-insensitively; status active restricts to active products.\n\n**Operation id:** `catalog_picker_search` — the same operation is `app.catalog.picker_search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/catalog_picker_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "catalog" ], "x-operation-kind": "query", "parameters": [ { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "scope", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "all", "title", "sku" ] } }, { "name": "vendor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "const": "active" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "storeId", "in": "query", "required": false, "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "exact", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "schema": { "default": "title_asc", "type": "string", "enum": [ "title_asc", "title_desc" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 800 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/catalog/picker/recent": { "get": { "operationId": "catalog_picker_recent", "summary": "catalog_picker_recent", "description": "The items most recently used in receipts, transfers or stock adjustments (`context`): up to 20 distinct live variants from the newest 200 lines or adjustments, grouped by product, newest first, with on-hand over every warehouse or one. Derived on every read, never stored.\n\n**Operation id:** `catalog_picker_recent` — the same operation is `app.catalog.picker_recent({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/catalog_picker_recent`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "catalog" ], "x-operation-kind": "query", "parameters": [ { "name": "context", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "receipt", "transfer", "adjust" ] } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/catalog/picker/variants": { "get": { "operationId": "catalog_picker_variants", "summary": "catalog_picker_variants", "description": "One product's live variants for the picker's detail pane, in the shop's variant order (Shopify's position; variants no sync has positioned yet first, in the order they were added; max 50 per page, keyset cursor), each with its options (name and value per product option) and the physical on-hand over every warehouse or one. Continues a search row whose variantsCapped is true from its variantsCursor.\n\n**Operation id:** `catalog_picker_variants` — the same operation is `app.catalog.picker_variants({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/catalog_picker_variants`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "catalog" ], "x-operation-kind": "query", "parameters": [ { "name": "productId", "in": "query", "required": true, "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 800 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/catalog/picker/vendors": { "get": { "operationId": "catalog_picker_vendors", "summary": "catalog_picker_vendors", "description": "The vendors of live products for the picker's chips: one per vendor (case-insensitive), in alphabetical order, 100 per page; `after` continues from the last vendor of a page, `text` narrows to a case-insensitive prefix.\n\n**Operation id:** `catalog_picker_vendors` — the same operation is `app.catalog.picker_vendors({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/catalog_picker_vendors`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "catalog" ], "x-operation-kind": "query", "parameters": [ { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/checkout-options": { "get": { "operationId": "checkout_options_list", "summary": "checkout_options_list", "description": "List the store's checkout options — every shipping option customers chose at checkout, learned from the orders (up to 200 of them; one bounded page, `cursor: null`) — needs review first, then the most recently chosen. Each row: the title the customer saw, source and code, `sourceKind` (shopify_rate, carrier_app, pickup, local_delivery, other), `target` (unreviewed, service, rules, no_label — a non-shipping option takes no label) with the mapped carrier account and service, the `revision` an edit sends back, open fulfillment orders (`openCount`, counted up to 500 with `openCapped`), orders of the last 30 days, first and last seen, and a `suggestion` for an unreviewed option (the mapping of the option a renamed rate replaced, or the service a person picked by hand for its last three labels). `overCap` counts options refused once the store holds the maximum: their orders follow the shipping rules. Filter by state, kind, when last seen or part of the title or code.\n\n**Operation id:** `checkout_options_list` — the same operation is `app.checkout.options_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/checkout_options_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "checkout-options" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Options in any of these states (needs_review, mapped, rules, no_label); absent = every state. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Options in any of these states (needs_review, mapped, rules, no_label); absent = every state.", "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "needs_review", "mapped", "rules", "no_label" ] } } }, { "name": "sources", "in": "query", "required": false, "description": "Options of any of these kinds (shopify_rate, carrier_app, pickup, local_delivery, other); absent = every kind. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Options of any of these kinds (shopify_rate, carrier_app, pickup, local_delivery, other); absent = every kind.", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shopify_rate", "carrier_app", "pickup", "local_delivery", "other" ] } } }, { "name": "seen", "in": "query", "required": false, "description": "`7d` / `30d`: chosen at checkout in the last 7 or 30 days; `stale`: not in 30 days.", "schema": { "description": "`7d` / `30d`: chosen at checkout in the last 7 or 30 days; `stale`: not in 30 days.", "type": "string", "enum": [ "7d", "30d", "stale" ] } }, { "name": "search", "in": "query", "required": false, "description": "Part of the option's title or code (case-insensitive).", "schema": { "description": "Part of the option's title or code (case-insensitive).", "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/checkout-options/target": { "post": { "operationId": "checkout_options_set_target", "summary": "checkout_options_set_target", "description": "Map a checkout option: ship its orders with one carrier service (`kind: service`, an account and a serviceCode from carriers_services_list), let the shipping rules decide (`kind: rules`), or mark it unreviewed again. Applies to every order with this option from the next rate call on; nothing already rated or bought changes. Send the option's `revision`: a stale one is refused as a conflict (revision_mismatch); asking for the mapping the option already has changes nothing. Refused: a non-shipping option (option_locked), a disconnected or freight account (carrier_account_unusable; needs_reauth is accepted), a code the account's catalogue does not list (unknown_service). Every change is recorded on the option's timeline.\n\n**Operation id:** `checkout_options_set_target` — the same operation is `app.checkout.options_set_target({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/checkout_options_set_target`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "checkout-options" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optionId": { "type": "string", "description": "document id of the checkout option.", "format": "floormode-id" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The option's revision, as checkout_options_list returned it." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "service" }, "carrierAccountId": { "type": "string", "description": "document id of the carrier account.", "format": "floormode-id" }, "serviceCode": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A serviceCode of that account from carriers_services_list." } }, "required": [ "kind", "carrierAccountId", "serviceCode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "rules" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unreviewed" } }, "required": [ "kind" ] } ] } }, "required": [ "optionId", "revision", "target" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/connections/disconnect": { "post": { "operationId": "local_stock_disconnect", "summary": "local_stock_disconnect", "description": "Disconnect a sibling connection as a HANDOVER rather than a switch (M16 W5b-F2). This is the operation the Settings → Integrations switch calls, and what it does depends on the peer's local-stock phase. ⚠️ SIDE EFFECTS: when the peer holds local stock here (phase `active`) it first CANCELS the peer's open component pick batches (picked units go back to their bins, `wo_pick_status: cancelled` goes out), then FREEZES that stock and queues the cutover snapshot — exactly local_stock_begin_disconnect — and deliberately LEAVES THE CONNECTION SWITCHED ON until the peer confirms the handback; the answer is `state: \"handing_back\"`. Calling it again while `disconnecting` re-derives and re-sends the same snapshot under the same idempotency key (the retry path for a rejected handback), never a second release, unless the peer refused that release as a `conflict` (its generation fence already holds a newer release, e.g. after this app was reinstalled): then the refused release is marked failed and the same frozen stock goes out under a new generation. Once the peer has acknowledged (phase `released`), or when it never held local stock at all (`inactive`), it writes the connection setting to false and answers `state: \"disconnected\"`. Turning a connection back ON is settings_set, which starts it fresh: nothing from the time it was off is sent later. REFUSALS (coded in `details.localRefusal`, and every one of them leaves the phase and the ledger exactly as they were — nothing is frozen and nothing is sent): `details.seamExit` — something only the peer or the floor can settle, every one named (a location Logistified still delegates here, the peer's items in an open transfer or pending receipt); `unmapped_warehouse_stock` — the peer's goods sit in a warehouse that maps to no Shopify location, and a handback states quantities per location, so they would simply be left out of the total; `no_writer_location` — an item holding no stock anywhere is handed back as a zero at every warehouse mapped as the inventory writer, and none is (map one under Settings → Warehouses first), so the item would be left out and the peer would keep its own stale number. A catalog larger than the 500 quantities one message may carry is not a refusal (contracts 1.6.0): the snapshot is split into verified parts the peer stages until the set is whole, so the handover stays all-or-nothing on both sides.\n\n**Operation id:** `local_stock_disconnect` — the same operation is `app.local.stock_disconnect({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_stock_disconnect`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "connections" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peer": { "type": "string", "enum": [ "logistified", "assemblified", "alertified" ] } }, "required": [ "peer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/costing/apply-receipt-cost": { "post": { "operationId": "costing_apply_receipt_cost", "summary": "costing_apply_receipt_cost", "description": "Roll the weighted-average unit cost forward for the received lines of a receipt and allocate a freight/duty total across them by value or weight. `lines` sets the base purchase unit cost per received variant (major currency units); freight+duty is split by the chosen method and folded into each line's receipt unit cost, which then updates the (variant, warehouse) weighted average. Runs once per receipt — a weighted average cannot be re-applied. Every received line of the receipt is costed or the call is refused; a line whose (variant, warehouse) position is already valued in a DIFFERENT currency is left untouched and reported in `skipped`, never blended.\n\n**Operation id:** `costing_apply_receipt_cost` — the same operation is `app.costing.apply_receipt_cost({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/costing_apply_receipt_cost`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "costing" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "description": "document id of the receipt to cost.", "format": "floormode-id" }, "lines": { "description": "Base purchase unit cost per received variant; missing lines default to 0.", "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "unitCost": { "type": "number", "minimum": 0 } }, "required": [ "variantId", "unitCost" ] } }, "freight": { "description": "Freight to allocate (default 0).", "type": "number", "minimum": 0 }, "duty": { "description": "Duty/other landed cost to allocate (default 0).", "type": "number", "minimum": 0 }, "method": { "description": "Allocate freight+duty by line value or by line weight (default value).", "type": "string", "enum": [ "value", "weight" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code the costs are priced in, e.g. EUR: three letters; lower case is accepted and upper-cased." } }, "required": [ "receiptId", "currency" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/costing/inventory-value": { "get": { "operationId": "costing_inventory_value", "summary": "costing_inventory_value", "description": "Recorded inventory cost per currency: current shelf weighted-average positions plus outstanding physical transfer quantities at frozen dispatch cost. Accepted, returned and lost quantities leave transit; cancellation alone does not. No COGS or revaluation. Reads at most five hundred current shelf cost positions and five hundred active transit lines, with separate cap flags; capped values are subtotals. Unknown cost/currency units are excluded and counted. Stock without any recorded cost position is outside shelf valuation.\n\n**Operation id:** `costing_inventory_value` — the same operation is `app.costing.inventory_value({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/costing_inventory_value`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "costing" ], "x-operation-kind": "query", "x-min-plan": "elevate", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/costing/margin-report": { "get": { "operationId": "costing_margin_report", "summary": "costing_margin_report", "description": "Shipped merchandise per SKU: units, verified discounted net line revenue snapshotted at shipment, booked weighted-average cost and their margin. Excludes shipping, fees and subsequent refunds. Unknown revenue makes its bucket revenue/margin null; known zero stays zero. revenueDecimals preserves source precision. Every SKU row and every entry in `totals` carries its currency — money is never summed across currencies, so the flat totalRevenue/totalCost/totalMargin scalars are null when the window holds more than one. Bounded scan with capped/scannedThrough disclosure; `unknownRevenueEntries` counts unverified net revenue, `unknownCostEntries` counts cost without a recorded currency, and `mixedCurrencyEntries` counts differing currencies.\n\n**Operation id:** `costing_margin_report` — the same operation is `app.costing.margin_report({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/costing_margin_report`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "costing" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Window start, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window start, epoch milliseconds (inclusive)." } }, { "name": "end", "in": "query", "required": true, "description": "Window end, epoch milliseconds (inclusive).", "schema": { "type": "number", "description": "Window end, epoch milliseconds (inclusive)." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/costing/variant-costs": { "get": { "operationId": "costing_variant_costs", "summary": "costing_variant_costs", "description": "Current weighted-average cost position per (variant, warehouse): unit cost, valued on-hand quantity and total valuation (max 200). Filter by variant and/or warehouse.\n\n**Operation id:** `costing_variant_costs` — the same operation is `app.costing.variant_costs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/costing_variant_costs`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "costing" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts": { "get": { "operationId": "counts_list", "summary": "counts_list", "description": "List cycle counts, in the chosen order (`sort`; newest first by default), one page, with counted-line and variance counters. Filter by status (open, counting, review, approved, cancelled) or warehouse. zoneId matches the task's zone SCOPE exactly, so a count scoped to explicit bins or to a whole warehouse is in no zone; stationId narrows to the station's warehouse.\n\n**Operation id:** `counts_list` — the same operation is `app.counts.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "open", "counting", "review", "approved", "cancelled" ] } } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "zoneId", "in": "query", "required": false, "description": "Counts scoped to this zone.", "schema": { "description": "Counts scoped to this zone.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "assignment", "in": "query", "required": false, "description": "mine = assigned to the caller or to nobody; all = everyone's.", "schema": { "description": "mine = assigned to the caller or to nobody; all = everyone's.", "type": "string", "enum": [ "mine", "all" ] } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "counts_create", "summary": "counts_create", "description": "Create a cycle count (`#CT-…`) over exactly one scope: binIds (max 200), zone or all. The expected quantities are a snapshot of the current bin projection, one line per (bin, item, lot) with stock on hand; `blind: true` hides them from the floor. `snapshotCapped` is true when a bin holds more stocked rows than one snapshot may read (100 per bin) — the count then covers part of that bin.\n\n**Operation id:** `counts_create` — the same operation is `app.counts.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "binIds": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "zone": { "type": "string" }, "all": { "type": "boolean" }, "blind": { "type": "boolean" } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/approve": { "post": { "operationId": "counts_approve", "summary": "counts_approve", "description": "Approve a reviewed count: every variance becomes one `count` ledger movement in the counted bin (uncounted lines are left alone). The variance applied is REBASED — counted minus (the snapshot plus everything the ledger did to that (bin, item, lot) since it was snapshotted) — so a receipt or pick during the count is not applied twice; a window too large to reconstruct refuses with `details.code: \"recount_required\"`. A count that finds fewer units than are reserved is applied and the holding allocation is trimmed and marked short. Variances beyond ±20% of the rebased expectation require acceptVariances: true. Idempotent per (count, bin, variant, lot). A variance on a LOCAL item (VMAT-/ASM-/CSTM-) mirrors the new levels to the owning peer, and is REFUSED with a coded `details.localRefusal` when the item stopped being ours between the scan and the approval (a disconnect in between) — the whole approval rolls back rather than posting half of it.\n\n**Operation id:** `counts_approve` — the same operation is `app.counts.approve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_approve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "acceptVariances": { "type": "boolean" }, "approvalId": { "description": "A lead's single-use grant for accept_count_difference, when variances beyond the guard are accepted by someone who does not hold floor.approve at the desk.", "type": "string", "format": "floormode-id" } }, "required": [ "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/cancel": { "post": { "operationId": "counts_cancel", "summary": "counts_cancel", "description": "Cancel a cycle count that has not been approved (open, counting or review). Nothing reaches the ledger and nothing is released — a count holds no reservation — while the snapshot and the counted quantities stay on the task as its record. Refused with `details.code: \"illegal_transition\"` once the count was approved (its variances were applied). Cancelling a cancelled count is a no-op.\n\n**Operation id:** `counts_cancel` — the same operation is `app.counts.cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string" } }, "required": [ "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/confirm-bin-empty": { "post": { "operationId": "counts_confirm_bin_empty", "summary": "counts_confirm_bin_empty", "description": "Confirm that a bin of the count's scope is empty (FT4-01). Only for a bin with no line on the count — the snapshot found it empty — so visiting it is part of the count's progress like counting a bin's lines; a bin with a line not at 0 is refused (count each item, 0 where none is left). Stock booked into the bin since the count was cut becomes one line per stocked row counted 0 (`zeroedLines`), a difference the review shows and the approval corrects. Confirming twice answers `confirmed: false`; an item recorded there later with `counts_record_count` moves the bin to its line.\n\n**Operation id:** `counts_confirm_bin_empty` — the same operation is `app.counts.confirm_bin_empty({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_confirm_bin_empty`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedBin": { "description": "Bin code or barcode.", "type": "string" } }, "required": [ "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/decide-lot-report": { "post": { "operationId": "counts_decide_lot_report", "summary": "counts_decide_lot_report", "description": "Decide a lot the floor reported on a count (`counts_get.reportedLots`, QA r1 L06-F06). `brought_in` creates the lot for the item (undated) and books the reported units into the bin as a stock correction (reason found), once; `dismissed` books nothing. Each report is decided once: the same decision again answers what was recorded, the other one is refused (count_report_decided). Answers { reportId, lotNumber, binCode, countedQty, decision, movementId }.\n\n**Operation id:** `counts_decide_lot_report` — the same operation is `app.counts.decide_lot_report({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_decide_lot_report`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reportId": { "type": "string", "minLength": 1, "description": "The report's id, as counts_get names it.", "format": "floormode-id" }, "decision": { "type": "string", "enum": [ "brought_in", "dismissed" ] } }, "required": [ "countTaskId", "reportId", "decision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/get": { "get": { "operationId": "counts_get", "summary": "counts_get", "description": "Get one cycle count: every snapshot line with its counted quantity and variance, plus the variance review list and whether approval needs acceptVariances. lotTrackedItems says whether one of the count's items tracks lots; with desk: true, whether any item does.\n\n**Operation id:** `counts_get` — the same operation is `app.counts.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "query", "parameters": [ { "name": "countTaskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "desk", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/record-count": { "post": { "operationId": "counts_record_count", "summary": "counts_record_count", "description": "Record one counted quantity. Bin and item are resolved server-side (binId/scannedBin, variantId/scannedCode); a variant that was not in the snapshot is added as a found row whose expectation is read from the CURRENT bin projection. A second count of the same (bin, item, lot) row REPLACES the first — the answer names it in `previousCountedQty`. Bins outside the count scope are rejected. A bin holding lot-tracked stock of the item needs the lot (lotId, or the scanned lotNumber of a lot the item already has), or the call is refused with `details.code: \"lot_required\"`: one count line is one (bin, item, lot). A count never creates a lot: a lot number the item does not have is refused with `details.code: \"lot_unknown\"`; report the find with `counts_report_lot` (E-0023).\n\n**Operation id:** `counts_record_count` — the same operation is `app.counts.record_count({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_record_count`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedBin": { "description": "Bin code or barcode.", "type": "string" }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedCode": { "description": "Item barcode or sku.", "type": "string" }, "lotId": { "description": "A lot the item has; `null` names the bin's untracked row when the bin also holds lots.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "lotNumber": { "description": "Lot number as scanned off the carton.", "type": "string" }, "countedQty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "method": { "description": "How the item was confirmed (scan, camera, typed, tap; desk for a desk caller). Omitted: scan with a code, tap without, desk for a desk caller. paper is refused.", "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "description": "A lead's single-use grant for a tap where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" } }, "required": [ "countTaskId", "countedQty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/reject": { "post": { "operationId": "counts_reject", "summary": "counts_reject", "description": "Send a reviewed count back to the floor; the counted quantities are kept.\n\n**Operation id:** `counts_reject` — the same operation is `app.counts.reject({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_reject`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string" } }, "required": [ "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/report-lot": { "post": { "operationId": "counts_report_lot", "summary": "counts_report_lot", "description": "Report a lot number the counter found in a bin that the item does not have (review 2026-09-14, E-0023). A count never creates a lot — `counts_record_count` refuses an unknown lot number — so this call records the find on the count task's timeline (`count_lot_reported`: lot, bin, item and the units seen, reason `lot_unknown`) for a manager to bring the lot in through receiving or a stock correction. Nothing is counted and no lot is created; a lot number the item already has is refused (count it instead). The report is also kept on the count (`counts_get.reportedLots`, at most 50 a count), where a manager decides it with counts_decide_lot_report.\n\n**Operation id:** `counts_report_lot` — the same operation is `app.counts.report_lot({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_report_lot`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotNumber": { "type": "string", "minLength": 1, "description": "Lot number as read off the carton." }, "countedQty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Units of that lot seen in the bin." }, "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedBin": { "description": "Bin code or barcode.", "type": "string" }, "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedCode": { "description": "Item barcode or sku.", "type": "string" }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "lotNumber", "countedQty", "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/counts/submit": { "post": { "operationId": "counts_submit", "summary": "counts_submit", "description": "Submit a count for review: computes the variances (counted − expected) and reports whether any of them exceeds the ±20% guard. A count is finished when every bin of its scope is done (each line counted, each bin without lines confirmed empty); sending it earlier needs `notCountedReason`, else it is refused with `details.code: \"count_incomplete\"`. Lines not counted stay NOT COUNTED — the approval never applies them as zero.\n\n**Operation id:** `counts_submit` — the same operation is `app.counts.submit({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/counts_submit`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "counts" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countTaskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "notCountedReason": { "description": "Why bins or lines were left: out_of_time, cannot_reach or other.", "type": "string", "enum": [ "out_of_time", "cannot_reach", "other" ] } }, "required": [ "countTaskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/customer-pages/brand": { "get": { "operationId": "customerPages_brand_get", "summary": "customerPages_brand_get", "description": "Read one store's customer brand (roadmap I-A): the three colours and their derived, WCAG-checked tokens, corners, the logo's size, the languages and the merchant's voice per language (e-mail intro, footer, sign-off), help links and address, the store's From address with its sending domain's state, and the store page's link settings. storeId is a store of the account (stores_list); omitted, the store the call acts as. A store that never saved a brand answers revision 0 with the account's legacy e-mail settings read as a brand, English only.\n\n**Operation id:** `customerPages_brand_get` — the same operation is `app.customerPages.brand_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/customerPages_brand_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "customer-pages" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "query", "required": false, "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "customerPages_brand_save", "summary": "customerPages_brand_save", "description": "Save one store's customer brand, which every customer e-mail of that store wears from then on. Pass expectedRevision from the latest read (0 before the first save); a stale one is refused revision_mismatch with the current revision. Refused as a field error: text on the background below 4.5:1 (the message names the nearest colour that passes), an unknown placeholder in an override ({store} and {order} where the key allows them), a default language the brand does not list. A From address at a hostname the account has not verified saves, and the store sends from the platform address until it is verified (domains_request).\n\n**Operation id:** `customerPages_brand_save` — the same operation is `app.customerPages.brand_save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/customerPages_brand_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "customer-pages" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "brand": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "accent": { "type": "string" }, "background": { "type": "string" }, "ink": { "type": "string" }, "corners": { "type": "string", "enum": [ "square", "soft", "round" ] }, "logo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 80, "maximum": 240 }, "align": { "type": "string", "enum": [ "left", "center" ] } }, "required": [ "width", "align" ] }, "locales": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "en", "de" ] } }, "defaultLocale": { "type": "string", "enum": [ "en", "de" ] }, "overrides": { "type": "object", "propertyNames": { "type": "string", "enum": [ "en", "de" ] }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "enum": [ "email.intro", "email.footer", "email.signoff", "slip.footer" ] }, "additionalProperties": { "type": "string" } } }, "help": { "type": "object", "properties": { "links": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } }, "required": [ "links", "email" ] }, "sender": { "anyOf": [ { "type": "object", "properties": { "address": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "address" ], "additionalProperties": false }, { "type": "null" } ] }, "storefront": { "type": "object", "properties": { "path": { "type": "string", "pattern": "^\\/(?:apps|a|community|tools)\\/[A-Za-z0-9_-]{1,30}$" }, "linkTarget": { "type": "string", "enum": [ "store", "carrier" ] } }, "required": [ "path", "linkTarget" ], "additionalProperties": false } }, "required": [ "name", "accent", "background", "ink", "corners", "logo", "locales", "defaultLocale", "overrides", "help", "sender", "storefront" ], "additionalProperties": false } }, "required": [ "expectedRevision", "brand" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/dashboard/needs-attention": { "get": { "operationId": "dashboard_needs_attention", "summary": "dashboard_needs_attention", "description": "The exception worklist for the home screen, ranked: orders on hold grouped by reason (with the covering document when the hold names one), orders the allocation engine could not fill (with the number of missing skus), side effects that did not go through — failed (dead), held while the peer is not answering, or expired out of the backlog — grouped by status and action with the affected document named, open shipping exceptions, and open orders that have not changed in over a week. Each group carries a count and up to three examples with a typed route (the Integrations health panel for side effects). Counts are per ORDER, not per hold. Every scan is bounded and discloses whether it was capped.\n\n**Operation id:** `dashboard_needs_attention` — the same operation is `app.dashboard.needs_attention({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dashboard_needs_attention`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "dashboard" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/dashboard/operation-cards": { "get": { "operationId": "dashboard_operation_cards", "summary": "dashboard_operation_cards", "description": "One card per warehouse operation for the home screen: how much work is waiting, how much of it is late and how much is blocked. `today` is the caller's local calendar day (YYYY-MM-DD) — the database has no timezone. receive = open receipts (late once a promised day lies before `today`, a promised instant lies before `dayStartMs` — the epoch ms at which `today` began for the caller — or an unpromised receipt is 3 days old) · pick = open pick batches (late after 24h) · pack = pack jobs waiting (blocked = failed jobs) · ship = labels to buy or print (blocked = open shipping exceptions) · count = open cycle counts (blocked = waiting for approval) · returns = return requests waiting for a decision. Every count comes from a bounded scan; `capped` says when one hit its budget.\n\n**Operation id:** `dashboard_operation_cards` — the same operation is `app.dashboard.operation_cards({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dashboard_operation_cards`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "dashboard" ], "x-operation-kind": "query", "parameters": [ { "name": "today", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "dayStartMs", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/dashboard/output": { "get": { "operationId": "dashboard_output", "summary": "dashboard_output", "description": "Today's output for the home screen: fulfillments (parcels) created today and yesterday, open fulfillment orders due before tomorrow (dueToday, which includes the late ones) and the ones already past their promise (late). The caller sends its local midnights as epoch ms (dayStartMs, previousDayStartMs, nextDayStartMs); every number is exact. While delivery dates are on (`deliveryDates`), work with a requested delivery date counts by its pack day in its warehouse's own day: dueToday = packed today or overdue, late = the pack day has passed; everything else by Shopify's fulfil-by against the caller's midnights. `packTime`: the team's pack time today in every warehouse, each on its own calendar day, with packing_time_summary's figures (parcels packed, the average within 30 minutes, the parcels over it) and `capped` when more warehouses exist than one read takes; no figure per person or per station.\n\n**Operation id:** `dashboard_output` — the same operation is `app.dashboard.output({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dashboard_output`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "dashboard" ], "x-operation-kind": "query", "parameters": [ { "name": "dayStartMs", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "previousDayStartMs", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "nextDayStartMs", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/dashboard/recent-events": { "get": { "operationId": "dashboard_recent_events", "summary": "dashboard_recent_events", "description": "The 20 newest change events of the shop — the dashboard feed without the counters.\n\n**Operation id:** `dashboard_recent_events` — the same operation is `app.dashboard.recent_events({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dashboard_recent_events`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "dashboard" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/dashboard/stats": { "get": { "operationId": "dashboard_stats", "summary": "dashboard_stats", "description": "Dashboard counters from bounded index scans: open orders, orders held by us, fulfillment orders due within 24h, fulfillments created today, variants at or below the low-stock threshold, plus the 20 newest change events. `capped` reports which scans hit their budget. Due = the end of the pack day (the warehouse's packing day before the customer's requested delivery day, in the warehouse's time zone) for work at a warehouse with a requested delivery date while delivery dates are on, else Shopify's fulfil-by.\n\n**Operation id:** `dashboard_stats` — the same operation is `app.dashboard.stats({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dashboard_stats`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "dashboard" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/disposition/damage": { "post": { "operationId": "disposition_record_damage", "summary": "disposition_record_damage", "description": "Move damaged / exception stock from its current bin into the warehouse's hospital / QA-hold bin (HOSP-01, created on first use — not pickable, not sellable) with a reason code and a real ledger movement (WHT-016). The source bin is required; any reservation on it travels with the goods. Defaults to the `damaged` reason. Pack-job references must use disposition_record_damage_bulk with the actual pack job ID. Dispositioning a LOCAL item (VMAT-/ASM-/CSTM-) mirrors the new levels to its owning peer, and is refused with a coded `details.localRefusal` when the item is frozen history or still unplaced — an archived one may still be drained.\n\n**Operation id:** `disposition_record_damage` — the same operation is `app.disposition.record_damage({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/disposition_record_damage`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "disposition" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "description": "document id of the variant (or scan a code).", "type": "string", "format": "floormode-id" }, "scannedCode": { "description": "Item barcode/sku (alternative to variantId).", "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fromBinId": { "description": "document id of the source bin.", "type": "string", "format": "floormode-id" }, "fromBinCode": { "description": "Source bin code (alternative to fromBinId).", "type": "string" }, "reasonCode": { "description": "Defaults to `damaged`.", "type": "string" }, "note": { "type": "string" }, "refType": { "description": "Link back to the work that surfaced the damage (closed set).", "type": "string", "enum": [ "warehouse_transfer", "physical_verification", "adjustment", "allocation", "allocation_line", "component_pick", "component_pick_unstage", "count_task", "damage", "import", "local_item_supersession", "local_item_twin_move", "local_stock_handback", "movement", "opening", "pack_job", "pick_line", "receipt", "return_receipt", "task" ] }, "refId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "approvalId": { "description": "A lead's single-use grant for mark_damaged (outside a desk lead).", "type": "string", "format": "floormode-id" } }, "required": [ "warehouseId", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/disposition/damage/bulk": { "post": { "operationId": "disposition_record_damage_bulk", "summary": "disposition_record_damage_bulk", "description": "Move a whole parcel's items (max 100) from ONE source bin into the warehouse's hospital / QA-hold bin in one transaction — the QC-fail flow at pack. One ledger movement per item; `applied`/`moved` say what moved and `skipped` names each item refused BEFORE its write with a coded reason (unknown_variant, insufficient_stock). A fault of the whole request (unknown bin, the hospital bin as source, an unknown reason, a variant listed twice) rolls the batch back whole. `requestKey` makes a retried call a verbatim replay; the same key with a different payload is a conflict (idempotency_key_reused). With refType pack_job, refId must be the real pack job ID: all remaining staged picks must match, QC must have failed, and the parcel is cancelled with an immutable disposition receipt. A new request key replays that same receipt only for the same payload. Damaged units become unreserved hospital stock for inspection; the order remains unfulfilled.\n\n**Operation id:** `disposition_record_damage_bulk` — the same operation is `app.disposition.record_damage_bulk({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/disposition_record_damage_bulk`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "disposition" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "variantId", "qty" ] }, "description": "The parcel's items; each variant at most once." }, "fromBinId": { "description": "document id of the source bin.", "type": "string", "format": "floormode-id" }, "fromBinCode": { "description": "Source bin code (alternative to fromBinId).", "type": "string" }, "reasonCode": { "description": "Defaults to `damaged`.", "type": "string" }, "note": { "type": "string" }, "refType": { "description": "Link back to the work that surfaced the damage (closed set).", "type": "string", "enum": [ "warehouse_transfer", "physical_verification", "adjustment", "allocation", "allocation_line", "component_pick", "component_pick_unstage", "count_task", "damage", "import", "local_item_supersession", "local_item_twin_move", "local_stock_handback", "movement", "opening", "pack_job", "pick_line", "receipt", "return_receipt", "task" ] }, "refId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "approvalId": { "description": "A lead's single-use grant for mark_damaged (outside a desk lead).", "type": "string", "format": "floormode-id" }, "requestKey": { "description": "Caller-minted idempotency key (e.g. a UUID), one per logical submit.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "warehouseId", "items" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/disposition/damaged": { "get": { "operationId": "disposition_list_damaged", "summary": "disposition_list_damaged", "description": "The stock currently held in a warehouse's hospital / QA-hold bin (WHT-016), by variant: onHand, reserved and available. Empty when the bin does not exist yet.\n\n**Operation id:** `disposition_list_damaged` — the same operation is `app.disposition.list_damaged({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/disposition_list_damaged`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "disposition" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/domains": { "get": { "operationId": "domains_list", "summary": "domains_list", "description": "List the account's sending domains (one row per e-mail hostname), their DNS records, state and provider readiness. Own tracking domains are deferred; a dark tracking row is retired on its next check.\n\n**Operation id:** `domains_list` — the same operation is `app.domains.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/domains_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "domains" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/domains/remove": { "post": { "operationId": "domains_remove", "summary": "domains_remove", "description": "Disable a domain immediately and durably remove its provider resource and hostname reservation. Refused (domain_in_use) while a store's brand still sends from it.\n\n**Operation id:** `domains_remove` — the same operation is `app.domains.remove({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/domains_remove`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "domains" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainId": { "type": "string", "description": "A merchantDomains id, e.g. \"merchantDomains_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "domainId", "generation" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/domains/request": { "post": { "operationId": "domains_request", "summary": "domains_request", "description": "Request a sending domain for the stores' From addresses (roadmap I-A). authorized: true states that Floormode may send the stores' transactional order e-mails from it (recorded with who stated it). A store's own primary domain is proven by Shopify's domain connection; any other hostname needs the _floormode TXT record before the provider creates it. kind tracking is refused (domain_kind_unavailable); myshopify.com and Floormode's own addresses are refused (domain_platform_host). Requesting a hostname the account has answers its row.\n\n**Operation id:** `domains_request` — the same operation is `app.domains.request({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/domains_request`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "domains" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tracking", "email" ] }, "hostname": { "type": "string", "maxLength": 300 }, "authorized": { "type": "boolean", "const": true } }, "required": [ "kind", "hostname", "authorized" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/domains/verify": { "post": { "operationId": "domains_verify", "summary": "domains_verify", "description": "Check a domain now (Check again): one DNS proof and one provider read; a failed or unstarted provider check is started again. Nothing re-checks on a clock: the provider's webhook, a refused send or this call arms each check.\n\n**Operation id:** `domains_verify` — the same operation is `app.domains.verify({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/domains_verify`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "domains" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainId": { "type": "string", "description": "A merchantDomains id, e.g. \"merchantDomains_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "domainId", "generation" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/entity-events": { "get": { "operationId": "entity_events_list", "summary": "entity_events_list", "description": "List the change timeline (entityEvents) of one entity, newest first (max 100). entityType is a closed set, e.g. \"order\", \"fulfillment_order\", \"product\", \"location\". A pick, pack or allocation fact is written once, on the order; a fulfillment order's timeline holds its own lifecycle (created, status, holds, splits). Stock writes no timeline: a bin's or an item's movements are inventory_movements (with onHandAfter), its reservations inventory_reservations. An archived order's timelines left with it: an empty one answers historyFromMs — read the order with history_order_get.\n\n**Operation id:** `entity_events_list` — the same operation is `app.entity.events_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/entity_events_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "entity-events" ], "x-operation-kind": "query", "parameters": [ { "name": "entityType", "in": "query", "required": true, "description": "Entity type, e.g. \"order\".", "schema": { "type": "string", "enum": [ "warehouse_transfer", "privacy_request", "alert", "automation_rule", "billing", "box", "carrier_account", "checkout_option", "count_task", "dom_rule", "dropship_po", "dropship_vendor", "freight_quote", "fulfillment", "fulfillment_order", "integration", "location", "location_type", "lot", "manifest", "note", "order", "pack_job", "pick_batch", "pickup", "product", "receipt", "return", "return_receipt", "return_request", "reverse_delivery", "reverse_fulfillment_order", "serial_unit", "settings", "shipment", "shipping_rule", "sku_slotting", "slotting_rule", "station", "store", "sync_health", "task", "variant", "warehouse", "wave", "work_order", "worker_profile", "zone", "person", "role", "floor_device" ], "description": "Entity type, e.g. \"order\"." } }, { "name": "entityId", "in": "query", "required": true, "description": "Entity id, e.g. the numeric Shopify order id.", "schema": { "type": "string", "description": "Entity id, e.g. the numeric Shopify order id.", "format": "floormode-id" } }, { "name": "store", "in": "query", "required": false, "description": "The store a Shopify id belongs to (`store.id` of an order). Absent: every store you see.", "schema": { "description": "The store a Shopify id belongs to (`store.id` of an order). Absent: every store you see.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/exceptions": { "get": { "operationId": "exceptions_list", "summary": "exceptions_list", "description": "List shipping exceptions (max 100 per page) with the shipment short id, order name and tracking number. Filter by a set of statuses (open, resolved), by shipment or by one `reason` code (the carrier's slug, e.g. failed_attempt); sort newest first (default) or oldest first; pass `cursor` back for the next page. `openCount` is the shipment scope's open total on the first page (it ignores `statuses` and `reason`), null on later pages.\n\n**Operation id:** `exceptions_list` — the same operation is `app.exceptions.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/exceptions_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "exceptions" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "open", "resolved" ] } } }, { "name": "shipmentId", "in": "query", "required": false, "description": "Only this shipment's exceptions.", "schema": { "description": "Only this shipment's exceptions.", "type": "string", "format": "floormode-id" } }, { "name": "reason", "in": "query", "required": false, "description": "One reason code, e.g. failed_attempt; absent = every reason.", "schema": { "description": "One reason code, e.g. failed_attempt; absent = every reason.", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "sort", "in": "query", "required": false, "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "schema": { "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "type": "string", "enum": [ "at:desc", "at:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/exceptions/resolve": { "post": { "operationId": "exceptions_resolve", "summary": "exceptions_resolve", "description": "Resolve one shipping exception; the optional note is recorded on the entry.\n\n**Operation id:** `exceptions_resolve` — the same operation is `app.exceptions.resolve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/exceptions_resolve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "exceptions" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exceptionId": { "type": "string", "description": "document id of the shipping exception.", "format": "floormode-id" }, "note": { "type": "string" } }, "required": [ "exceptionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/forecast/reorder": { "get": { "operationId": "forecast_reorder_suggestions", "summary": "forecast_reorder_suggestions", "description": "Low-stock reorder suggestions for a warehouse: for every SKU selling from it, the velocity (units/day over the window), the reorder point (velocity × (lead + safety days)), the on-hand/available position, the suggested top-up quantity to the target coverage / slotting max, and the days of cover. Only SKUs at/below their reorder point are returned, biggest suggestion first. Bounded + cap-disclosed (`scanned`/`capped`).\n\n**Operation id:** `forecast_reorder_suggestions` — the same operation is `app.forecast.reorder_suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/forecast_reorder_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "forecast" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } }, { "name": "windowDays", "in": "query", "required": false, "description": "Demand window; defaults to 30, at most 365.", "schema": { "description": "Demand window; defaults to 30, at most 365.", "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "leadTimeDays", "in": "query", "required": false, "description": "Supplier lead time; defaults to 14.", "schema": { "description": "Supplier lead time; defaults to 14.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "safetyStockDays", "in": "query", "required": false, "description": "Safety coverage; defaults to 7.", "schema": { "description": "Safety coverage; defaults to 7.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "targetCoverageDays", "in": "query", "required": false, "description": "Coverage a reorder tops up to; defaults to 45.", "schema": { "description": "Coverage a reorder tops up to; defaults to 45.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/forecast/reorder-po": { "post": { "operationId": "forecast_draft_reorder_po", "summary": "forecast_draft_reorder_po", "description": "Flag a low-stock SKU to the procurement seam (Alertified reorder event + a variant timeline entry). Advisory: a true Logistified PO-draft contract is the live-gate follow-up. The result states where the alert went: switchedOff=true means Alertified is switched off, so the alert is on this shop's alert list only and nothing was sent — switching Alertified on later does not send it.\n\n**Operation id:** `forecast_draft_reorder_po` — the same operation is `app.forecast.draft_reorder_po({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/forecast_draft_reorder_po`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "forecast" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "note": { "type": "string" } }, "required": [ "warehouseId", "variantId", "quantity" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/forecast/transfer": { "get": { "operationId": "forecast_transfer_suggestions", "summary": "forecast_transfer_suggestions", "description": "Multi-warehouse transfer suggestions: for each SKU, rebalance spare stock from warehouses above their reorder point to those below it, never pushing a source below its own reorder point. Each row carries the variant, from/to warehouse, quantity and the source's coverage after the move. Bounded + cap-disclosed. Materialize one with forecast_create_transfer_task.\n\n**Operation id:** `forecast_transfer_suggestions` — the same operation is `app.forecast.transfer_suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/forecast_transfer_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "forecast" ], "x-operation-kind": "query", "parameters": [ { "name": "windowDays", "in": "query", "required": false, "description": "Demand window; defaults to 30, at most 365.", "schema": { "description": "Demand window; defaults to 30, at most 365.", "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "leadTimeDays", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "safetyStockDays", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "targetCoverageDays", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/forecast/transfer-task": { "post": { "operationId": "forecast_create_transfer_task", "summary": "forecast_create_transfer_task", "description": "Materialize a transfer suggestion as a `move` task from one warehouse to another (deduped per variant → destination: one open rebalance at a time).\n\n**Operation id:** `forecast_create_transfer_task` — the same operation is `app.forecast.create_transfer_task({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/forecast_create_transfer_task`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "forecast" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromWarehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "toWarehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "fromWarehouseId", "toWarehouseId", "variantId", "quantity" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/freight/quotes": { "get": { "operationId": "freight_quotes_list", "summary": "freight_quotes_list", "description": "List freight quotes, newest first (max 100), with the order name and a derived `expired` flag (the quote's time-bound window has elapsed). Filter by status (open, booking, booked, expired, cancelled) or by the order they belong to. Each quote carries its handling units, region-aware classification (NMFC class / density or loading meters / pallet spaces / chargeable weight) and the collected carrier offers.\n\n**Operation id:** `freight_quotes_list` — the same operation is `app.freight.quotes_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/freight_quotes_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "freight" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "booking", "booked", "expired", "cancelled" ] } }, { "name": "orderId", "in": "query", "required": false, "description": "document id of the order.", "schema": { "description": "document id of the order.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/freight/quotes/cancel": { "post": { "operationId": "freight_quotes_cancel", "summary": "freight_quotes_cancel", "description": "Cancel an open (or expired) freight quote so it stops showing as bookable. Refused as a conflict for a quote that has already been booked into a shipment, and for one whose tender is still being attempted (`booking`) — wait for that attempt to settle first.\n\n**Operation id:** `freight_quotes_cancel` — the same operation is `app.freight.quotes_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/freight_quotes_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "freight" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "document id of the freight quote.", "format": "floormode-id" } }, "required": [ "quoteId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/freight/quotes/get": { "get": { "operationId": "freight_quotes_get", "summary": "freight_quotes_get", "description": "Get one freight quote with its handling units, region-aware classification, the collected offers (carrier, service, amount, transit, expiry), the booked offer/shipment (once booked) and the BOL documents. Returns null for an unknown quote.\n\n**Operation id:** `freight_quotes_get` — the same operation is `app.freight.quotes_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/freight_quotes_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "freight" ], "x-operation-kind": "query", "parameters": [ { "name": "quoteId", "in": "query", "required": true, "description": "document id of the freight quote.", "schema": { "type": "string", "description": "document id of the freight quote.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/books": { "get": { "operationId": "history_books_list", "summary": "history_books_list", "description": "The history archive's books of one year (the stock ledger and the cost of goods sold, one part per day; the lot book, per ship month): per book and month the parts, rows and bytes, from the year's manifest. Download a month as gzip CSV from GET /api/history/books/{book}/{YYYY-MM}.\n\n**Operation id:** `history_books_list` — the same operation is `app.history.books_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_books_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "year", "in": "query", "required": true, "description": "The calendar year, `YYYY`.", "schema": { "type": "string", "pattern": "^\\d{4}$", "description": "The calendar year, `YYYY`." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/orders/detail": { "get": { "operationId": "history_order_get", "summary": "history_order_get", "description": "Read an order that left Floormode for the history archive (closed, and past the tenant's hot window, history_status tier.days): { state: \"hot\" } while Floormode still holds it (read it with orders_get), { state: \"none\" } when the archive holds no copy, or { state: \"archived\", order } with its newest copy: the facts (numbers, lines, fulfilments, shipments, pick and pack facts as person ids, COGS) and the customer part (name, addresses, notes, tags). customerState says whether that part is kept, erased by a privacy request, or absent (none, or past its six years); people names the person ids now.\n\n**Operation id:** `history_order_get` — the same operation is `app.history.order_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_order_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Shopify's numeric order id as a string (\"450789469\").", "schema": { "type": "string", "pattern": "^\\d{1,20}$", "description": "Shopify's numeric order id as a string (\"450789469\").", "format": "floormode-id" } }, { "name": "store", "in": "query", "required": false, "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "schema": { "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "type": "string" } }, { "name": "life", "in": "query", "required": false, "description": "The newest archived copy even while the order is in Floormode again (a restored order): its earlier pick and pack history.", "schema": { "description": "The newest archived copy even while the order is in Floormode again (a restored order): its earlier pick and pack history.", "type": "string", "const": "archived" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/orders/evidence": { "get": { "operationId": "history_order_evidence", "summary": "history_order_evidence", "description": "The evidence an archived order still has in Floormode, inside its own window: the pack photos (the warehouse's photo retention), the customer's return photos (with returns.view) and the bills of lading (with shipping.labels or floor.pack). Metadata only; open the bytes with GET /api/packing/photos/{photoId}, /api/returns/evidence/{evidenceId} and /api/shipping/documents/{documentId}. Empty once Shopify deleted the order or a privacy request erased its customer.\n\n**Operation id:** `history_order_evidence` — the same operation is `app.history.order_evidence({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_order_evidence`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Shopify's numeric order id as a string (\"450789469\").", "schema": { "type": "string", "pattern": "^\\d{1,20}$", "description": "Shopify's numeric order id as a string (\"450789469\").", "format": "floormode-id" } }, { "name": "store", "in": "query", "required": false, "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "schema": { "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Pass this as a JSON-encoded object.", "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "packPhotos", "returnPhotos", "documents" ] }, "cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The kind's `cursor` from the previous answer." } }, "required": [ "kind", "cursor" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/orders/packing-slip": { "get": { "operationId": "history_packing_slip", "summary": "history_packing_slip", "description": "The original packing slip of an archived order's parcel, from the archive: the lines that went into the box, the pack job's code and tracking, and — while the customer part is kept — the address and the order note. { state: \"none\" } when the archive holds no such parcel. The PDF: GET /api/history/orders/{shopifyOrderId}/packing-slip.pdf?packJobId=….\n\n**Operation id:** `history_packing_slip` — the same operation is `app.history.packing_slip({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_packing_slip`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Shopify's numeric order id as a string (\"450789469\").", "schema": { "type": "string", "pattern": "^\\d{1,20}$", "description": "Shopify's numeric order id as a string (\"450789469\").", "format": "floormode-id" } }, { "name": "store", "in": "query", "required": false, "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "schema": { "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "type": "string" } }, { "name": "packJobId", "in": "query", "required": true, "description": "The parcel: a pack job of the archived order (`facts.packJobs[]._id` of history_order_get).", "schema": { "type": "string", "description": "The parcel: a pack job of the archived order (`facts.packJobs[]._id` of history_order_get).", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/orders/restore": { "post": { "operationId": "history_order_restore", "summary": "history_order_restore", "description": "Bring an archived order back into Floormode, e.g. for a goodwill return: Floormode reads it from Shopify again and mirrors it as a new copy. A restored closed order fires no automation rule and sends no customer notification again, and stays for 90 days. { state: \"staged\" } once its Shopify copy is on its way in (it appears within seconds), { state: \"hot\" } when Floormode holds it already. Its earlier pick and pack history stays readable with history_order_get.\n\n**Operation id:** `history_order_restore` — the same operation is `app.history.order_restore({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_order_restore`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "pattern": "^\\d{1,20}$", "description": "Shopify's numeric order id as a string (\"450789469\").", "format": "floormode-id" }, "store": { "description": "The order's store: `store.id` of the search hit or lot ship that named it. Absent: every live store, home store first.", "type": "string" } }, "required": [ "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/orders/search": { "get": { "operationId": "history_orders_search", "summary": "history_orders_search", "description": "Find orders in Shopify — including ones that left Floormode for the history archive — by order number, customer name or e-mail, or SKU (Shopify's own order search). Each hit: shopifyOrderId, name, created, closed and cancelled instants, payment and fulfilment status, total; open one with history_order_get. capped past the first 20 hits.\n\n**Operation id:** `history_orders_search` — the same operation is `app.history.orders_search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_orders_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What Shopify's order search takes: an order number (#1001 or 1001), a customer's name or e-mail, a SKU.", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What Shopify's order search takes: an order number (#1001 or 1001), a customer's name or e-mail, a SKU." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/privacy-orders": { "get": { "operationId": "history_privacy_orders", "summary": "history_privacy_orders", "description": "The archived orders of a privacy export (Art. 15), page by page, once its privacy_exportPage walk is complete: every archived copy of each order the request names, facts and customer part, as export records (table archivedOrders). An erased customer part is stated, never read. nextCursor null after the last page.\n\n**Operation id:** `history_privacy_orders` — the same operation is `app.history.privacy_orders({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_privacy_orders`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "parameters": [ { "name": "requestId", "in": "query", "required": true, "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "sessionId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "cursor", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "object", "properties": { "order": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "life": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "order", "life" ] }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/history/status": { "get": { "operationId": "history_status", "summary": "history_status", "description": "The history archive as it stands: its rollout (off, copy, on), the last nightly pass, the books copied through, the orders kept in Floormode per reason (open work, a document that never ended, a lot month not yet booked, restored, too large), the orders that left with a document that never ended, and the next run.\n\n**Operation id:** `history_status` — the same operation is `app.history.status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "history" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/holds": { "get": { "operationId": "holds_list", "summary": "holds_list", "description": "List our fulfillment-order hold intents (max 100). Filter by status (pending_apply, active, pending_release, released, failed) or by Shopify order id. Holds placed by other apps are mirrored on the fulfillment order, not listed here.\n\n**Operation id:** `holds_list` — the same operation is `app.holds.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/holds_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "holds" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_apply", "active", "pending_release", "released", "failed" ] } }, { "name": "shopifyOrderId", "in": "query", "required": false, "description": "Numeric Shopify order id as a string.", "schema": { "description": "Numeric Shopify order id as a string.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "holds_apply", "summary": "holds_apply", "description": "Hold one fulfillment order (identified by shopifyFoId or its document id). Records the intent with a `#HOLD-…` handle and queues the Shopify call; the reason maps to Shopify's hold reasons (payment_pending → AWAITING_PAYMENT, fraud_risk → HIGH_RISK_OF_FRAUD, address_issue → INCORRECT_ADDRESS, awaiting_stock → INVENTORY_OUT_OF_STOCK, awaiting_production/awaiting_supplier/customer_request/other → OTHER). The two waiting reasons take an optional `linkRef` naming the purchase, transfer or work order the hold waits for, which the order screen shows instead of a bare \"on hold\". Re-applying while a hold is pending or active returns the existing handle.\n\n**Operation id:** `holds_apply` — the same operation is `app.holds.apply({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/holds_apply`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "holds" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "foDocId": { "type": "string", "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "shopifyFoId": { "description": "Numeric Shopify fulfillment order id.", "type": "string", "format": "floormode-id" }, "reason": { "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "linkRef": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "po", "to", "wo", "bom" ], "description": "Purchase order, transfer order, work order, or (M15) the BOM a sales allocation is waiting to have built when no work order exists yet." }, "ref": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The document number, e.g. PO-1042." }, "label": { "description": "Optional human line shown with it.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "kind", "ref" ], "description": "The covering document this hold waits for. Floormode owns no PO/WO documents (Logistified and Assemblified do), so this is a merchant-readable reference, not a link." }, "source": { "description": "Defaults to manual.", "type": "string", "enum": [ "manual", "rule" ] }, "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/holds/apply-for-orders": { "post": { "operationId": "holds_apply_for_orders", "summary": "holds_apply_for_orders", "description": "Hold whole orders in ONE transaction (max 500 per call): every open fulfillment order Shopify allows to be held gets our hold intent, with the same reason mapping as holds_apply. `applied` counts the newly held fulfillment orders; orders that contributed none are listed in `skipped` with a reason (unknown_order, no_holdable_fulfillment_order, already_on_hold, batch_budget_exhausted — the per-call write budget ran out before that order; resubmit it) instead of failing the batch. Pass a `requestKey` (one per logical submit, kept across retries) and a retry answers the stored result verbatim; the same key with a different payload is a conflict (idempotency_key_reused).\n\n**Operation id:** `holds_apply_for_orders` — the same operation is `app.holds.apply_for_orders({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/holds_apply_for_orders`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "holds" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "Numeric Shopify order ids as strings." }, "reason": { "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "linkRef": { "description": "One covering document for the whole batch, e.g. the purchase order everything in this selection waits for.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "po", "to", "wo", "bom" ], "description": "Purchase order, transfer order, work order, or (M15) the BOM a sales allocation is waiting to have built when no work order exists yet." }, "ref": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The document number, e.g. PO-1042." }, "label": { "description": "Optional human line shown with it.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "kind", "ref" ] }, "requestKey": { "description": "Caller-minted idempotency key (e.g. a UUID), one per logical submit.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "shopifyOrderIds", "reason" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/holds/release": { "post": { "operationId": "holds_release", "summary": "holds_release", "description": "Release one of our holds. Queues the Shopify release; the intent goes to released once Shopify confirms it (or the next fulfillment-order snapshot does).\n\n**Operation id:** `holds_release` — the same operation is `app.holds.release({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/holds_release`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "holds" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holdIntentId": { "type": "string", "description": "document id of the hold intent.", "format": "floormode-id" } }, "required": [ "holdIntentId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/holds/release-for-orders": { "post": { "operationId": "holds_release_for_orders", "summary": "holds_release_for_orders", "description": "Release our holds on whole orders in ONE transaction (max 500 per call): every pending or active hold intent of each order is queued for release. Holds placed by other apps stay untouched. Orders without a hold of ours are listed in `skipped` (unknown_order, no_active_hold, batch_budget_exhausted — resubmit that order). `requestKey` makes a retried call a verbatim replay, exactly as on holds_apply_for_orders.\n\n**Operation id:** `holds_release_for_orders` — the same operation is `app.holds.release_for_orders({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/holds_release_for_orders`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "holds" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "Numeric Shopify order ids as strings." }, "requestKey": { "description": "Caller-minted idempotency key (e.g. a UUID), one per logical submit.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "shopifyOrderIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/integrations/health": { "get": { "operationId": "integrations_health", "summary": "integrations_health", "description": "Health of every sibling integration in one read (M15 T8): per peer the connection switch, the inbound receipt ledger (applied / rejected, last message received) and the outbound queue (pending, in-flight, parked, expired, failed, done, oldest parked message, throttled rows and the next attempt time). Plus the single-writer picture: `writerGaps` lists warehouses that can receive goods but write no Shopify inventory while Logistified is connected — a location NO app writes — and `matrix` says which app owns which Shopify number given what is currently switched on. Aggregates only; no message payloads.\n\n**Operation id:** `integrations_health` — the same operation is `app.integrations.health({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/integrations_health`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "integrations" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/integrations/outbox/redrive": { "post": { "operationId": "outbox_redrive", "summary": "outbox_redrive", "description": "Manually redrive one terminal outbound message (`failed` or `expired` in the outbox): resets it to `pending` with a fresh attempt budget, cleared throttle and transport streaks and a fresh attempt lineage, records the redrive on the sync-health timeline and arms the drain in the same transaction. The delivery runs again under its own idempotency key, so a message the destination already applied settles as a replay, not a duplicate. Refuses (`conflict`) rows that are not terminal, and rows the peer refused for their stored bytes (`refusalCode` `invalid_body`, `invalid_envelope`, `segment_mismatch`, `part_hash_mismatch` or `conflict`): a redrive resends the same bytes and would fail the same way. Also refuses an Alertified alert: an alert describes a moment that has passed and stays on the shop's own alert list.\n\n**Operation id:** `outbox_redrive` — the same operation is `app.outbox.redrive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/outbox_redrive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "integrations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outboxId": { "type": "string", "description": "document id of the terminal outbox row.", "format": "floormode-id" } }, "required": [ "outboxId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/integrations/outbox/terminal": { "get": { "operationId": "outbox_terminal_list", "summary": "outbox_terminal_list", "description": "Terminal outbound messages (`failed` or `expired` in the outbox) of ONE destination: a sibling peer, or `shopify` for the Shopify updates a merchant may send again (order refresh, stock push, order tags, fulfillment order move). Newest death first (`settledAt`), with the attempt lineage a redrive decision needs: attempts, transport failures, the last error, the claim stamp and the attempt fingerprint. A disclosed page (`rows`/`capped`/`cursor`). Each row carries the peer's `refusalCode` that ended it (null when none was coded) and `redrivable`, false when that refusal concerned the stored bytes or the message is an alert (never sent again), which `outbox_redrive` refuses; `countShortId` is a count export's count number (else null); a Shopify row names its `order` (number and Shopify id) or its `item` (variant and warehouse).\n\n**Operation id:** `outbox_terminal_list` — the same operation is `app.outbox.terminal_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/outbox_terminal_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "integrations" ], "x-operation-kind": "query", "parameters": [ { "name": "destination", "in": "query", "required": true, "description": "The sibling peer, or `shopify`, whose terminal rows to list.", "schema": { "type": "string", "enum": [ "logistified", "assemblified", "alertified", "shopify" ], "description": "The sibling peer, or `shopify`, whose terminal rows to list." } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page (max 50).", "schema": { "default": 20, "description": "Rows per page (max 50).", "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` the previous page answered with (keyset continuation).", "schema": { "description": "The `cursor` the previous page answered with (keyset continuation).", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory": { "get": { "operationId": "inventory_by_variant", "summary": "inventory_by_variant", "description": "Stock per variant (cursor pages, max 50 rows each): onHand, bin reserved, physicalFree and nullable available plus a per-warehouse rollup across Shopify and connected-app items. Available protects unallocated channel commitments; null and availabilityReason mean channel evidence is pending or incomplete. PhysicalFree remains sellable bin stock minus physical reservations. Optional source filter and search over sku, barcode, product and variant title. Each row also carries `committed` (units owed by open, unfulfilled fulfillment orders) and `incoming` (unreceived remainder of the open receipts). Both are NULLABLE, and null means unknown, not zero: it is returned only when the underlying bounded scan hit its ceiling and this variant was not in what came back. When the scan completed, a variant with nothing owed or arriving is 0. Use inventory_atp for the per-warehouse split of the same two buckets, and inventory_by_variant_total for the exact number of items under the same filters. Each row carries the item's `dangerousGoods` (class and UN number); `dangerousGoods` as a filter keeps the items marked as one of the given classes.\n\n**Operation id:** `inventory_by_variant` — the same operation is `app.inventory.by_variant({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_by_variant`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Words of an item's title, SKU or barcode, each matching a word's start. Exact SKU or barcode first, then title matches, whatever the sort.", "schema": { "description": "Words of an item's title, SKU or barcode, each matching a word's start. Exact SKU or barcode first, then title matches, whatever the sort.", "type": "string", "maxLength": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's cursor, under the same sort and filters.", "schema": { "description": "The previous page's cursor, under the same sort and filters.", "type": "string", "maxLength": 512 } }, { "name": "sort", "in": "query", "required": false, "description": "`id:asc` (the order items were added in, the default), `item:asc` (product then variant title, A to Z) or `item:desc` (Z to A).", "schema": { "description": "`id:asc` (the order items were added in, the default), `item:asc` (product then variant title, A to Z) or `item:desc` (Z to A).", "type": "string", "enum": [ "id:asc", "item:asc", "item:desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 50.", "schema": { "description": "Rows per page, at most 50.", "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "source", "in": "query", "required": false, "description": "Catalog source; omit for all warehouse items.", "schema": { "description": "Catalog source; omit for all warehouse items.", "type": "string", "enum": [ "shopify", "assemblified_virtual_material", "assemblified_sub_assembly", "logistified_custom_item" ] } }, { "name": "customs", "in": "query", "required": false, "description": "Shopify items by customs information: `complete` (base HS code and origin), `missing_hs` or `missing_origin`. Omit for every item.", "schema": { "description": "Shopify items by customs information: `complete` (base HS code and origin), `missing_hs` or `missing_origin`. Omit for every item.", "type": "string", "enum": [ "complete", "missing_hs", "missing_origin" ] } }, { "name": "tracking", "in": "query", "required": false, "description": "Items by what they record: `none`, `lot` or `serial`. Omit for every item.", "schema": { "description": "Items by what they record: `none`, `lot` or `serial`. Omit for every item.", "type": "string", "enum": [ "none", "lot", "serial" ] } }, { "name": "scanning", "in": "query", "required": false, "description": "Items by how Floor Mode confirms them: `blocked` (no barcode, SKU or alias, not allowed without a scan) or `no_scan`. Omit for every item.", "schema": { "description": "Items by how Floor Mode confirms them: `blocked` (no barcode, SKU or alias, not allowed without a scan) or `no_scan`. Omit for every item.", "type": "string", "enum": [ "blocked", "no_scan" ] } }, { "name": "dangerousGoods", "in": "query", "required": false, "description": "Items marked as one of these dangerous-goods classes: `lithium_in_equipment`, `lithium_with_equipment`, `lithium_alone`, `limited_quantity`, `regulated`. Omit for every item. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Items marked as one of these dangerous-goods classes: `lithium_in_equipment`, `lithium_with_equipment`, `lithium_alone`, `limited_quantity`, `regulated`. Omit for every item.", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "lithium_in_equipment", "lithium_with_equipment", "lithium_alone", "limited_quantity", "regulated" ] } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/adjust": { "post": { "operationId": "inventory_adjust", "summary": "inventory_adjust", "description": "Adjust the stock of one variant in one bin. Identify the bin by binId or binCode (+warehouseId when ambiguous) and the variant by variantId, sku or barcode. Pass exactly one of delta (relative) or setTo (absolute). reasonCode is required and must be a known adjustment reason. LOTS: the bin projection is per lot, so a bin holding lot-tracked stock of the item needs an explicit lotId/lotNumber, and setTo needs one for an item that tracks lots (a bin has no single absolute quantity of it) — both refuse with `details.code: \"lot_required\"` rather than adjusting a lot-less row that holds nothing.\n\n**Operation id:** `inventory_adjust` — the same operation is `app.inventory.adjust({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_adjust`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "binCode": { "type": "string" }, "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "lotId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lotNumber": { "description": "An existing lot number of the item.", "type": "string" }, "delta": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "setTo": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasonCode": { "type": "string", "minLength": 1 }, "note": { "type": "string" }, "idempotencyKey": { "description": "Repeating a key is a no-op.", "type": "string" } }, "required": [ "reasonCode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/adjustment-reasons": { "get": { "operationId": "inventory_adjustment_reasons", "summary": "inventory_adjustment_reasons", "description": "List the adjustment reasons — a fixed vocabulary, the same for every tenant, in picker order (damaged, lost, found, shrinkage, sample, correction, expired). inventory_adjust accepts exactly these codes; there are no custom reasons.\n\n**Operation id:** `inventory_adjustment_reasons` — the same operation is `app.inventory.adjustment_reasons({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_adjustment_reasons`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/atp": { "get": { "operationId": "inventory_atp", "summary": "inventory_atp", "description": "Available-to-promise breakdown for one variant: per-warehouse onHand, reserved (bin allocation), committed (open unfulfilled order units — derived, distinct from reserved), physicalFree (sellable stock minus bin reservations), available (channel-adjusted capacity, nullable with availabilityReason) and incoming, plus tenant-wide totals. `incoming` is the unreceived remainder (expected − received) of the open receipts — receipts that are cancelled or already fully received are excluded — and `incomingSources` names the documents behind it, each carrying the `receiptId` to fetch it with (null for the purchase_order/transfer seam kinds, which have no receipt here yet). The `supplier` and `onOrder` buckets are a declared seam for supplier-held and on-order stock: they are always 0 today because purchase orders live in Logistified, not here. `localHold` is non-null only for a LOCAL item (VMAT-/ASM-/CSTM-) whose units Floormode may not promise — `local_stock_frozen` (handed back to its owner on a disconnect), `item_unplaced` (its opening quantity has never been placed) or `catalog_unconfirmed` (no catalog record has named it). `available` is 0 whenever it is set, while `onHand` stays truthful: the units are on the shelf and have to be drainable, they are simply not ours to sell.\n\n**Operation id:** `inventory_atp` — the same operation is `app.inventory.atp({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_atp`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/backlog-shortfall": { "get": { "operationId": "inventory_backlog_shortfall", "summary": "inventory_backlog_shortfall", "description": "What has to be ordered to clear the backlog: per sku, the units owed by open unfulfilled orders (demand), what is in the bins (available), what is already on its way (incoming), the resulting shortfall and a suggested order quantity (demand − available − incoming, floored at 0). Worst shortfall first, 50 rows by default. This measures orders that EXIST; forecast_reorder_suggestions is the predictive counterpart. `capped` reports which scans hit their budget.\n\n**Operation id:** `inventory_backlog_shortfall` — the same operation is `app.inventory.backlog_shortfall({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_backlog_shortfall`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows to return (default 50).", "schema": { "description": "Rows to return (default 50).", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "includeCovered", "in": "query", "required": false, "description": "Also list skus whose backlog is fully covered by stock on hand. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Also list skus whose backlog is fully covered by stock on hand.", "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/bin-lots": { "get": { "operationId": "inventory_bin_lots", "summary": "inventory_bin_lots", "description": "The lots one bin currently holds of one variant (max 50 rows, `capped` says when more exist): lotId, lotNumber, expiryDate, onHand. Live stock, not a count snapshot — what a floor count must name before it books a lot-tracked row.\n\n**Operation id:** `inventory_bin_lots` — the same operation is `app.inventory.bin_lots({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_bin_lots`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "binId", "in": "query", "required": true, "description": "document id of the bin.", "schema": { "type": "string", "description": "document id of the bin.", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/capacity-proofs/request": { "post": { "operationId": "inventory_requestCapacityProofs", "summary": "inventory_requestCapacityProofs", "description": "Ask Shopify again for the reserved stock of the items a stock page shows (up to 100 item and warehouse pairs). Only an item that already uses capacity proofs, whose proof is no longer current and that has no request outstanding is asked for; every other pair is skipped. Answers how many were asked for. Does not alter physical stock.\n\n**Operation id:** `inventory_requestCapacityProofs` — the same operation is `app.inventory.requestCapacityProofs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_requestCapacityProofs`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pairs": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "warehouseId", "variantId" ] } } }, "required": [ "pairs" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/channel-observation/refresh": { "post": { "operationId": "inventory_requestChannelObservation", "summary": "inventory_requestChannelObservation", "description": "Request a fresh Shopify named-state inventory observation for one mapped item and warehouse. Verifies a terminal transfer uncertainty only when no live transfer obligation remains. Runs through the durable reconciler and does not alter physical stock.\n\n**Operation id:** `inventory_requestChannelObservation` — the same operation is `app.inventory.requestChannelObservation({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_requestChannelObservation`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "warehouseId", "variantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/import": { "post": { "operationId": "inventory_import_stock", "summary": "inventory_import_stock", "description": "Import counted stock into one warehouse (max 500 rows per call). Rows are {sku|barcode, binCode, qty, tracking?}; `tracking` (none | lot | serial) sets the item's tracking mode as variants_set_tracking does (one mode per item per sheet; a bundle is refused), and the row's stock is still booked without a lot. Mode 'set' (default) treats qty as the counted quantity, 'add' as a delta. Unknown bins/skus are returned in `errors` while valid rows are applied. SIDE EFFECTS: an applied row posts an `import` stock movement and, for a LOCAL item (VMAT-/ASM-/CSTM-), sends the owning peer an absolute local_inventory_snapshot mirror. A local row Floormode may not write — handed back on a disconnect, still on the unplaced worklist, or a catalog placeholder — is REPORTED in `errors` like any other bad row and never silently skipped; place its opening quantity through local_items_place_opening first.\n\n**Operation id:** `inventory_import_stock` — the same operation is `app.inventory.import_stock({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_import_stock`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "rows": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "barcode": { "type": "string" }, "binCode": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tracking": { "type": "string", "enum": [ "none", "lot", "serial" ] } }, "required": [ "binCode", "qty" ] } }, "mode": { "type": "string", "enum": [ "set", "add" ] }, "idempotencyKey": { "description": "Caller-minted replay key, kept across retries of one submission: the same sheet under the same key answers the original result verbatim (replayed: true, original referenceId, applied, errors) and books nothing, indefinitely; the same key with a different warehouse, mode or rows is a conflict (idempotency_key_reused).", "type": "string", "minLength": 1 } }, "required": [ "warehouseId", "rows" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/move": { "post": { "operationId": "inventory_move", "summary": "inventory_move", "description": "Move stock of one variant between two bins of the same warehouse. Fails when the source has too little available stock (unless the warehouse allows negative stock). A source bin holding lot-tracked stock needs an explicit lotId/lotNumber (`details.code: \"lot_required\"`) — the lot travels with the goods.\n\n**Operation id:** `inventory_move` — the same operation is `app.inventory.move({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_move`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromBinId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "toBinId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lotId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lotNumber": { "description": "An existing lot number of the item.", "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "note": { "type": "string" }, "idempotencyKey": { "description": "Repeating a key is a no-op.", "type": "string" } }, "required": [ "fromBinId", "toBinId", "variantId", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/movements": { "get": { "operationId": "inventory_movements", "summary": "inventory_movements", "description": "Read one page of the stock ledger in the chosen order (`sort`; newest first by default) (the answer is { rows, capped, cursor } — pass `cursor` back to continue). Filter by binId (both directions) or variantId; without a filter the tenant-wide ledger is returned. `kinds` (receipt, putaway, pick, pack, ship, adjust, count, return, move, release, import, opening), `reasonCode` and the window `atFromMs`/`atToMs` (milliseconds since 1970, half-open) narrow the result — all applied before the page is cut. Once older rows left for the history archive, an answer whose window reaches below them names `historyFromMs` (every row from it on is here) and `historyKinds`. Read for one bin or one item, newest first with no kind, reason or end filter, each row carries `onHandAfter`: the bin's units (an item's, with `variantId` too), or the item's units in the movement's warehouse, after it, computed from the ledger, and `onHandChange` what the movement did to it (+ in, − out, 0 a move inside); both null on any other read, the balance also on a row older than `historyFromMs`.\n\n**Operation id:** `inventory_movements` — the same operation is `app.inventory.movements({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_movements`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": false, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "binId", "in": "query", "required": false, "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "kinds", "in": "query", "required": false, "description": "Any of these movement kinds, e.g. adjust + import; absent = every kind. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these movement kinds, e.g. adjust + import; absent = every kind.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "receipt", "putaway", "pick", "pack", "ship", "adjust", "count", "return", "move", "release", "import", "opening" ] } } }, { "name": "reasonCode", "in": "query", "required": false, "description": "Adjustment reason code, e.g. damaged.", "schema": { "description": "Adjustment reason code, e.g. damaged.", "type": "string" } }, { "name": "atFromMs", "in": "query", "required": false, "description": "Movements at or after this instant (milliseconds since 1970, UTC).", "schema": { "description": "Movements at or after this instant (milliseconds since 1970, UTC).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "atToMs", "in": "query", "required": false, "description": "Movements before this instant (milliseconds since 1970, UTC).", "schema": { "description": "Movements before this instant (milliseconds since 1970, UTC).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "sort", "in": "query", "required": false, "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "schema": { "description": "`at:desc` (newest first, the default) or `at:asc` (oldest first).", "type": "string", "enum": [ "at:desc", "at:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/opening-import": { "get": { "operationId": "inventory_opening_job", "summary": "inventory_opening_job", "description": "The warehouse's latest opening-stock import, from the job row: status (running/done/failed), rows imported, rows skipped (variants that already had non-opening movements in the warehouse), the continuation cursor, the error and the timestamps — or null when the warehouse never ran one. Warehouse-scoped so a reload finds its job without a jobId; this is what the onboarding card renders.\n\n**Operation id:** `inventory_opening_job` — the same operation is `app.inventory.opening_job({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_opening_job`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "inventory_opening_import", "summary": "inventory_opening_import", "description": "Start or resume opening stock for a linked warehouse that has not gone live. The Worker fetches fresh Shopify named inventory states into an immutable paged manifest (up to 800 levels per request); repeat while inventory_opening_job says sourceComplete:false. No physical stock is booked until every source page is complete. The durable openingImport run then books pages without the browser. Only explicit on_hand is imported; missing/inconsistent physical, committed or unavailable states are reported with counts and an affected-item sample. Sellable units go to UNASSIGNED-01, unavailable units to non-sellable quarantine, preserving named source states. Opening movements suppress Shopify pushes. Existing counted stock is preserved and per-warehouse/variant replay keys prevent double booking. Observe inventory_opening_job for completion; a completed source-issue report can be retried with a new fresh fetch. Passing jobId manually advances this warehouse's ready booking job; another warehouse's job is not_found. Going live is a separate fresh quantity and ownership verification, never implied by import completion.\n\n**Operation id:** `inventory_opening_import` — the same operation is `app.inventory.opening_import({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_opening_import`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "document id of the warehouse (must be linked).", "format": "floormode-id" }, "jobId": { "description": "Advance this warehouse's running import by one page; omit to start.", "type": "string", "format": "floormode-id" }, "restartSource": { "description": "Restart incomplete source pagination; refused after source completion. Booked stock is never reset.", "type": "boolean" }, "targetBinId": { "description": "Put every sellable unit into this pick bin of the warehouse instead of UNASSIGNED-01 (honoured when the job is opened).", "type": "string", "format": "floormode-id" } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/opening-template": { "get": { "operationId": "inventory_opening_template", "summary": "inventory_opening_template", "description": "Prefilled opening-stock sheet rows for one linked warehouse, from the Shopify inventory-levels mirror: {sku, barcode, title, shopifyOnHand} per variant with stock at the linked location (explicit on_hand only). Missing physical source quantities are reported as blockedCount and a bounded blockedItems sample; a download must refuse a partial sheet. Paged by cursor/nextCursor (max 200 rows). Intended for a downloadable CSV with an empty binCode column that feeds inventory_import_stock.\n\n**Operation id:** `inventory_opening_template` — the same operation is `app.inventory.opening_template({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_opening_template`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse (must be linked).", "schema": { "type": "string", "description": "document id of the warehouse (must be linked).", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "description": "Keyset cursor from the previous page's `nextCursor`.", "schema": { "description": "Keyset cursor from the previous page's `nextCursor`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/physical-verification": { "get": { "operationId": "inventory_physicalVerification", "summary": "inventory_physicalVerification", "description": "Read the latest physical stock verification, complete bin and lot scope, source evidence and recovery status for an inventory pair.\n\n**Operation id:** `inventory_physicalVerification` — the same operation is `app.inventory.physicalVerification({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_physicalVerification`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": true, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/physical-verification/begin": { "post": { "operationId": "inventory_beginPhysicalVerification", "summary": "inventory_beginPhysicalVerification", "description": "Start a complete physical inventory review. Loads current Shopify source records before the merchant verifies every bin and lot.\n\n**Operation id:** `inventory_beginPhysicalVerification` — the same operation is `app.inventory.beginPhysicalVerification({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_beginPhysicalVerification`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "restart": { "type": "boolean" } }, "required": [ "warehouseId", "variantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/physical-verification/confirm": { "post": { "operationId": "inventory_confirmPhysicalVerification", "summary": "inventory_confirmPhysicalVerification", "description": "Verify all physical bin and lot counts. Explicit named-state preparation compares and corrects damaged or quality-control stock; only quarantine preparation may classify reviewed unmapped bins. Named-state corrections can change Shopify on-hand. A fresh source readback and full count precede the immutable on-hand correction that resumes sync without replacing checkout commitments.\n\n**Operation id:** `inventory_confirmPhysicalVerification` — the same operation is `app.inventory.confirmPhysicalVerification({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_confirmPhysicalVerification`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verificationId": { "type": "string", "description": "A inventoryPhysicalVerifications id, e.g. \"inventoryPhysicalVerifications_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "counts": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "quantityId": { "type": "string", "description": "A binQuantities id, e.g. \"binQuantities_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "countedQuantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "quantityId", "countedQuantity" ] } }, "physicallyVerified": { "type": "boolean", "const": true }, "prepareQualityControl": { "type": "boolean" }, "prepareNamedState": { "type": "string", "enum": [ "quality_control", "damaged" ] }, "qualityControlBinIds": { "maxItems": 200, "type": "array", "items": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } }, "required": [ "verificationId", "counts", "physicallyVerified" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/physical-verification/retry": { "post": { "operationId": "inventory_retryPhysicalVerification", "summary": "inventory_retryPhysicalVerification", "description": "Recover an interrupted physical verification using its exact original Shopify request and idempotency key.\n\n**Operation id:** `inventory_retryPhysicalVerification` — the same operation is `app.inventory.retryPhysicalVerification({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_retryPhysicalVerification`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verificationId": { "type": "string", "description": "A inventoryPhysicalVerifications id, e.g. \"inventoryPhysicalVerifications_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "verificationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/place": { "post": { "operationId": "inventory_place_stock", "summary": "inventory_place_stock", "description": "Moves stock OUT of the unassigned bin into real bins — never sets a count. Every row goes through the stock door; a limit, product rule, mix rule, missing lot or short source refuses the WHOLE batch as one conflict. Only free units move. The batch is bound to its idempotencyKey: a retry with other rows is a conflict.\n\n**Operation id:** `inventory_place_stock` — the same operation is `app.inventory.place_stock({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_place_stock`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" }, "rows": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lotId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "toBinId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "variantId", "toBinId", "qty" ] } }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "warehouseId", "rows", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/place-suggestions": { "get": { "operationId": "inventory_place_suggestions", "summary": "inventory_place_suggestions", "description": "Proposed bins for one page of the unassigned bin, planned under the warehouse's putaway strategy with the room earlier rows of the page were promised. Nothing is booked; inventory_place_stock books exactly the proposals a merchant confirms. `unplacedQty` names units nothing fits; `scanComplete` false means more bins exist than were ranked.\n\n**Operation id:** `inventory_place_suggestions` — the same operation is `app.inventory.place_suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_place_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } }, { "name": "seed", "in": "query", "required": true, "description": "The batch key the proposals are ranked by.", "schema": { "type": "string", "maxLength": 80, "description": "The batch key the proposals are ranked by." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/reservations": { "get": { "operationId": "inventory_reservations", "summary": "inventory_reservations", "description": "Read one page of the reservations of a bin (`binId`) or of an item in every bin (`variantId`), newest first: the allocation lines of current and past orders (max 25 rows; the answer is { rows, capped, cursor } — pass `cursor` back to continue). Each row names its order, its allocation and its state (`status`: released gave the units back, consumed shipped them, `releasedReason` says why), the units it holds (`qty`, picked ones in `pickedQty`), could not reserve (`shortQty`) and gave back (`releasedQty`), when it was reserved (`createdAt`) and when its allocation last changed (`updatedAt`).\n\n**Operation id:** `inventory_reservations` — the same operation is `app.inventory.reservations({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_reservations`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "binId", "in": "query", "required": false, "description": "The bin whose reservations to list.", "schema": { "description": "The bin whose reservations to list.", "type": "string", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": false, "description": "The item whose reservations to list, in every bin.", "schema": { "description": "The item whose reservations to list, in every bin.", "type": "string", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string", "maxLength": 24 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/stock-exists": { "get": { "operationId": "inventory_stock_exists", "summary": "inventory_stock_exists", "description": "Whether any unit is on hand anywhere in the tenant — one bounded probe over the bin quantities, {exists}. What the opening-stock onboarding card decides from, so it never derives 'no stock yet' from the page of inventory.by_variant it happens to show.\n\n**Operation id:** `inventory_stock_exists` — the same operation is `app.inventory.stock_exists({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_stock_exists`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/stock-journey": { "get": { "operationId": "inventory_stock_journey", "summary": "inventory_stock_journey", "description": "One item's stock journey per active warehouse: Shopify's available at the warehouse's location as last read and when (`shopifySays`), the sellable number Floormode writes (`weSay`), and the state since when: in step, a difference the nightly check found that Floormode did not cause, a difference in the last read, Floormode's own change still on its way, a refused update, waiting for Shopify's open orders, not managed here, or not read yet. `shopifyAdminUrl` is the item's page in Shopify's admin when the difference is the merchant's to settle.\n\n**Operation id:** `inventory_stock_journey` — the same operation is `app.inventory.stock_journey({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_stock_journey`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "Document id of the variant.", "schema": { "type": "string", "description": "Document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/sync-status": { "get": { "operationId": "inventory_sync_status", "summary": "inventory_sync_status", "description": "Bounded per-warehouse inventory delivery and verification status for one variant. Reports stored blocks and pending work; it does not assert current Shopify totals or attribute discrepancies to an actor.\n\n**Operation id:** `inventory_sync_status` — the same operation is `app.inventory.sync_status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_sync_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "Document id of the variant.", "schema": { "type": "string", "description": "Document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/total": { "get": { "operationId": "inventory_by_variant_total", "summary": "inventory_by_variant_total", "description": "The exact number of live items inventory_by_variant lists under the same source, customs and tracking filters (no search): {total}. Counts items, not stock.\n\n**Operation id:** `inventory_by_variant_total` — the same operation is `app.inventory.by_variant_total({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_by_variant_total`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "source", "in": "query", "required": false, "description": "Catalog source; omit for all warehouse items.", "schema": { "description": "Catalog source; omit for all warehouse items.", "type": "string", "enum": [ "shopify", "assemblified_virtual_material", "assemblified_sub_assembly", "logistified_custom_item" ] } }, { "name": "customs", "in": "query", "required": false, "description": "Shopify items by customs information: `complete` (base HS code and origin), `missing_hs` or `missing_origin`. Omit for every item.", "schema": { "description": "Shopify items by customs information: `complete` (base HS code and origin), `missing_hs` or `missing_origin`. Omit for every item.", "type": "string", "enum": [ "complete", "missing_hs", "missing_origin" ] } }, { "name": "tracking", "in": "query", "required": false, "description": "Items by what they record: `none`, `lot` or `serial`. Omit for every item.", "schema": { "description": "Items by what they record: `none`, `lot` or `serial`. Omit for every item.", "type": "string", "enum": [ "none", "lot", "serial" ] } }, { "name": "scanning", "in": "query", "required": false, "description": "Items by how Floor Mode confirms them: `blocked` (no barcode, SKU or alias, not allowed without a scan) or `no_scan`. Omit for every item.", "schema": { "description": "Items by how Floor Mode confirms them: `blocked` (no barcode, SKU or alias, not allowed without a scan) or `no_scan`. Omit for every item.", "type": "string", "enum": [ "blocked", "no_scan" ] } }, { "name": "dangerousGoods", "in": "query", "required": false, "description": "Items marked as one of these dangerous-goods classes: `lithium_in_equipment`, `lithium_with_equipment`, `lithium_alone`, `limited_quantity`, `regulated`. Omit for every item. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Items marked as one of these dangerous-goods classes: `lithium_in_equipment`, `lithium_with_equipment`, `lithium_alone`, `limited_quantity`, `regulated`. Omit for every item.", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "lithium_in_equipment", "lithium_with_equipment", "lithium_alone", "limited_quantity", "regulated" ] } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/unassigned": { "get": { "operationId": "inventory_unassigned_contents", "summary": "inventory_unassigned_contents", "description": "One page of what still lies in the warehouse's unassigned bin (UNASSIGNED-01): item, lot, on hand and free units, keyset by variant and lot. The placement table's rows.\n\n**Operation id:** `inventory_unassigned_contents` — the same operation is `app.inventory.unassigned_contents({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_unassigned_contents`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/untracked-ownership/review": { "post": { "operationId": "inventory_reviewUntrackedOwnership", "summary": "inventory_reviewUntrackedOwnership", "description": "Confirm the physically reviewed existing local quantity of a Shopify untracked item. Records local-only ownership without changing stock or publishing to Shopify; refuses changed evidence or pending obligations.\n\n**Operation id:** `inventory_reviewUntrackedOwnership` — the same operation is `app.inventory.reviewUntrackedOwnership({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_reviewUntrackedOwnership`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmedOnHand": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "warehouseId", "variantId", "expectedFingerprint", "confirmedOnHand" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/inventory/variant-bins": { "get": { "operationId": "inventory_variant_bins", "summary": "inventory_variant_bins", "description": "Per-bin stock breakdown for one variant (max 200 rows).\n\n**Operation id:** `inventory_variant_bins` — the same operation is `app.inventory.variant_bins({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/inventory_variant_bins`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "inventory" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/jobs": { "get": { "operationId": "jobs_list", "summary": "jobs_list", "description": "List merchant-recoverable background updates with safe status messages and the next scheduled run (runAtMs, epoch ms). Internal maintenance jobs and raw failure details are excluded.\n\n**Operation id:** `jobs_list` — the same operation is `app.jobs.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/jobs_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "jobs" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/jobs/retry": { "post": { "operationId": "jobs_retry", "summary": "jobs_retry", "description": "Resume one stopped merchant background update using its existing scheduled work. Running updates cannot be retried; an already queued retry returns retried:false.\n\n**Operation id:** `jobs_retry` — the same operation is `app.jobs.retry({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/jobs_retry`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "jobs" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "string", "enum": [ "ingestRecovery", "channelObservation", "inventoryMetadata", "allocationReplan", "componentConsumption" ] } }, "required": [ "job" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-printer-profiles": { "get": { "operationId": "label_printer_profiles_list", "summary": "label_printer_profiles_list", "description": "List printer and medium calibration profiles in bounded cursor pages.\n\n**Operation id:** `label_printer_profiles_list` — the same operation is `app.label.printer_profiles_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_printer_profiles_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-printer-profiles" ], "x-operation-kind": "query", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "label_printer_profiles_save", "summary": "label_printer_profiles_save", "description": "Create or revise a printer calibration profile independently of label artwork; updates require the current revision.\n\n**Operation id:** `label_printer_profiles_save` — the same operation is `app.label.printer_profiles_save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_printer_profiles_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-printer-profiles" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "printerName": { "type": "string", "minLength": 1, "maxLength": 120 }, "mediumName": { "type": "string", "minLength": 1, "maxLength": 120 }, "calibration": { "type": "object", "properties": { "offsetXmm": { "default": 0, "type": "number", "minimum": -20, "maximum": 20 }, "offsetYmm": { "default": 0, "type": "number", "minimum": -20, "maximum": 20 }, "scaleXpercent": { "default": 100, "type": "number", "minimum": 90, "maximum": 110 }, "scaleYpercent": { "default": 100, "type": "number", "minimum": 90, "maximum": 110 } } }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "create" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "update" }, "profileId": { "type": "string", "description": "A labelPrinterProfiles id, e.g. \"labelPrinterProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "profileId", "expectedRevision" ] } ] } }, "required": [ "name", "printerName", "mediumName", "calibration", "target" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-printer-profiles/delete": { "post": { "operationId": "label_printer_profiles_delete", "summary": "label_printer_profiles_delete", "description": "Soft-delete a printer profile at the expected revision.\n\n**Operation id:** `label_printer_profiles_delete` — the same operation is `app.label.printer_profiles_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_printer_profiles_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-printer-profiles" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "A labelPrinterProfiles id, e.g. \"labelPrinterProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "profileId", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-printer-profiles/get": { "get": { "operationId": "label_printer_profiles_get", "summary": "label_printer_profiles_get", "description": "Read the current printer profile revision, or null if deleted.\n\n**Operation id:** `label_printer_profiles_get` — the same operation is `app.label.printer_profiles_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_printer_profiles_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-printer-profiles" ], "x-operation-kind": "query", "parameters": [ { "name": "profileId", "in": "query", "required": true, "description": "A labelPrinterProfiles id, e.g. \"labelPrinterProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A labelPrinterProfiles id, e.g. \"labelPrinterProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-templates": { "get": { "operationId": "label_templates_list", "summary": "label_templates_list", "description": "List tenant-shared label designs, newest first. Follow cursor for subsequent bounded pages.\n\n**Operation id:** `label_templates_list` — the same operation is `app.label.templates_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_templates_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-templates" ], "x-operation-kind": "query", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "label_templates_create", "summary": "label_templates_create", "description": "Save a tenant-shared reusable label design. Copies and starting slot belong to each print run and are not saved. An image element names an image the label designer stored, by its digest (`image.sha256`); the design never carries its bytes.\n\n**Operation id:** `label_templates_create` — the same operation is `app.label.templates_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_templates_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-templates" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "options": { "type": "object", "properties": { "paper": { "default": "a4", "type": "string", "enum": [ "a4", "letter", "thermal" ] }, "widthMm": { "default": 57, "type": "number", "minimum": 0.1, "maximum": 300 }, "heightMm": { "default": 32, "type": "number", "minimum": 0.1, "maximum": 300 }, "marginXmm": { "default": 19.5, "type": "number", "minimum": 0, "maximum": 50 }, "marginYmm": { "default": 20.5, "type": "number", "minimum": 0, "maximum": 50 }, "marginRightMm": { "type": "number", "minimum": 0, "maximum": 50 }, "marginBottomMm": { "type": "number", "minimum": 0, "maximum": 50 }, "thermalColumns": { "type": "integer", "minimum": 1, "maximum": 10 }, "gapXmm": { "default": 0, "type": "number", "minimum": 0, "maximum": 20 }, "gapYmm": { "default": 0, "type": "number", "minimum": 0, "maximum": 20 }, "barcodeType": { "default": "auto", "type": "string", "enum": [ "auto", "code128", "ean13", "ean8", "upca", "code39", "itf", "upce", "gs1_128", "qrcode", "datamatrix", "pdf417", "gs1_datamatrix" ] }, "showTitle": { "default": true, "type": "boolean" }, "showSubtitle": { "default": true, "type": "boolean" }, "showBarcodeText": { "default": true, "type": "boolean" }, "layout": { "type": "object", "properties": { "widthMm": { "type": "number", "minimum": 0.1, "maximum": 300 }, "heightMm": { "type": "number", "minimum": 0.1, "maximum": 300 }, "elements": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "image" }, "fit": { "type": "string", "enum": [ "contain" ] }, "image": { "type": "object", "properties": { "sha256": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$" }, "mime": { "type": "string", "enum": [ "image/png", "image/jpeg" ] }, "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1024 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1024 }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 65536 } }, "required": [ "sha256", "mime", "width", "height", "bytes" ], "additionalProperties": false } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "fit", "image" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rectangle", "ellipse", "line" ] }, "strokeWidthMm": { "type": "number", "minimum": 0, "maximum": 3 }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "fill": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "shape", "strokeWidthMm", "stroke", "fill" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "text" }, "content": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "field" }, "field": { "type": "string", "enum": [ "title", "subtitle", "barcode", "sku", "productTitle", "variantTitle", "price", "lotNumber", "expiryDate", "binCode", "warehouseName", "zone" ] } }, "required": [ "kind", "field" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "static" }, "text": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "text" ], "additionalProperties": false } ] }, "fontSizePt": { "type": "number", "minimum": 4, "maximum": 100 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "weight": { "type": "string", "enum": [ "normal", "bold" ] } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "content", "fontSizePt", "align", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "barcode" }, "content": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "field" }, "field": { "type": "string", "enum": [ "title", "subtitle", "barcode", "sku", "productTitle", "variantTitle", "price", "lotNumber", "expiryDate", "binCode", "warehouseName", "zone" ] } }, "required": [ "kind", "field" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "static" }, "text": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "text" ], "additionalProperties": false } ] }, "showValue": { "type": "boolean" } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "content", "showValue" ], "additionalProperties": false } ] } } }, "required": [ "widthMm", "heightMm", "elements" ], "additionalProperties": false } } } }, "required": [ "name", "options" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-templates/delete": { "post": { "operationId": "label_templates_delete", "summary": "label_templates_delete", "description": "Soft-delete a saved label design when expectedRevision matches.\n\n**Operation id:** `label_templates_delete` — the same operation is `app.label.templates_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_templates_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-templates" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "description": "A labelTemplates id, e.g. \"labelTemplates_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "templateId", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-templates/get": { "get": { "operationId": "label_templates_get", "summary": "label_templates_get", "description": "Read a saved label design and its optimistic revision, or null when absent or deleted.\n\n**Operation id:** `label_templates_get` — the same operation is `app.label.templates_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_templates_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-templates" ], "x-operation-kind": "query", "parameters": [ { "name": "templateId", "in": "query", "required": true, "description": "A labelTemplates id, e.g. \"labelTemplates_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A labelTemplates id, e.g. \"labelTemplates_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/label-templates/update": { "post": { "operationId": "label_templates_update", "summary": "label_templates_update", "description": "Replace a saved label design when expectedRevision matches. A stale edit returns conflict and preserves the newer design.\n\n**Operation id:** `label_templates_update` — the same operation is `app.label.templates_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_templates_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "label-templates" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "description": "A labelTemplates id, e.g. \"labelTemplates_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "options": { "type": "object", "properties": { "paper": { "default": "a4", "type": "string", "enum": [ "a4", "letter", "thermal" ] }, "widthMm": { "default": 57, "type": "number", "minimum": 0.1, "maximum": 300 }, "heightMm": { "default": 32, "type": "number", "minimum": 0.1, "maximum": 300 }, "marginXmm": { "default": 19.5, "type": "number", "minimum": 0, "maximum": 50 }, "marginYmm": { "default": 20.5, "type": "number", "minimum": 0, "maximum": 50 }, "marginRightMm": { "type": "number", "minimum": 0, "maximum": 50 }, "marginBottomMm": { "type": "number", "minimum": 0, "maximum": 50 }, "thermalColumns": { "type": "integer", "minimum": 1, "maximum": 10 }, "gapXmm": { "default": 0, "type": "number", "minimum": 0, "maximum": 20 }, "gapYmm": { "default": 0, "type": "number", "minimum": 0, "maximum": 20 }, "barcodeType": { "default": "auto", "type": "string", "enum": [ "auto", "code128", "ean13", "ean8", "upca", "code39", "itf", "upce", "gs1_128", "qrcode", "datamatrix", "pdf417", "gs1_datamatrix" ] }, "showTitle": { "default": true, "type": "boolean" }, "showSubtitle": { "default": true, "type": "boolean" }, "showBarcodeText": { "default": true, "type": "boolean" }, "layout": { "type": "object", "properties": { "widthMm": { "type": "number", "minimum": 0.1, "maximum": 300 }, "heightMm": { "type": "number", "minimum": 0.1, "maximum": 300 }, "elements": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "image" }, "fit": { "type": "string", "enum": [ "contain" ] }, "image": { "type": "object", "properties": { "sha256": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$" }, "mime": { "type": "string", "enum": [ "image/png", "image/jpeg" ] }, "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1024 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1024 }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 65536 } }, "required": [ "sha256", "mime", "width", "height", "bytes" ], "additionalProperties": false } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "fit", "image" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rectangle", "ellipse", "line" ] }, "strokeWidthMm": { "type": "number", "minimum": 0, "maximum": 3 }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "fill": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "shape", "strokeWidthMm", "stroke", "fill" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "text" }, "content": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "field" }, "field": { "type": "string", "enum": [ "title", "subtitle", "barcode", "sku", "productTitle", "variantTitle", "price", "lotNumber", "expiryDate", "binCode", "warehouseName", "zone" ] } }, "required": [ "kind", "field" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "static" }, "text": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "text" ], "additionalProperties": false } ] }, "fontSizePt": { "type": "number", "minimum": 4, "maximum": 100 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "weight": { "type": "string", "enum": [ "normal", "bold" ] } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "content", "fontSizePt", "align", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "xMm": { "type": "number", "minimum": 0, "maximum": 300 }, "yMm": { "type": "number", "minimum": 0, "maximum": 300 }, "widthMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "heightMm": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "rotationDeg": { "type": "integer", "minimum": 0, "maximum": 359 }, "kind": { "type": "string", "const": "barcode" }, "content": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "field" }, "field": { "type": "string", "enum": [ "title", "subtitle", "barcode", "sku", "productTitle", "variantTitle", "price", "lotNumber", "expiryDate", "binCode", "warehouseName", "zone" ] } }, "required": [ "kind", "field" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "static" }, "text": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "text" ], "additionalProperties": false } ] }, "showValue": { "type": "boolean" } }, "required": [ "id", "xMm", "yMm", "widthMm", "heightMm", "kind", "content", "showValue" ], "additionalProperties": false } ] } } }, "required": [ "widthMm", "heightMm", "elements" ], "additionalProperties": false } } } }, "required": [ "templateId", "expectedRevision", "name", "options" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/day-plans": { "get": { "operationId": "day_plans_grid", "summary": "day_plans_grid", "description": "One warehouse's day plans over 7 or 14 days from `startDay` (from 14 days back to 28 ahead, in the warehouse's time zone): the people who work there (warehouse scope `all`, or a worker profile in the warehouse; with a floor task type their role allows), each with what they may do (task types, zones, home station, pick profile and lock), their plans per day (areas in order: a task type with an optional zone, station or pick profile, and on Elevate a target), the revision and who changed it last, and per area whether it lies outside what the person may do (`task`, `zone`, `locked`, or `removed` when the zone, station or profile is gone). On Elevate the day's team targets too. A plan never refuses or assigns work: it orders and defaults the person's floor. No performance figures.\n\n**Operation id:** `day_plans_grid` — the same operation is `app.day.plans_grid({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plans_grid`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "startDay", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "days", "in": "query", "required": true, "schema": { "type": "number", "enum": [ 7, 14 ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/day-plans/copy": { "post": { "operationId": "day_plans_copy", "summary": "day_plans_copy", "description": "Copies days of a warehouse's plans onto other days, one pair per target day (at most 7, each from today to 28 days ahead): every person's plan of `from` onto `to`, only onto empty days unless `replace` (then the target day becomes the source, and an empty source day clears it). Areas travel verbatim, targets included. Answers the counts: copied, kept (a target day that already had a plan), cleared, skipped (a person no longer in the warehouse, or a plan naming a place that is gone).\n\n**Operation id:** `day_plans_copy` — the same operation is `app.day.plans_copy({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plans_copy`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "pairs": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ] } }, "replace": { "type": "boolean" } }, "required": [ "warehouseId", "pairs", "replace" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/day-plans/distribute": { "post": { "operationId": "day_plan_targets_distribute", "summary": "day_plan_targets_distribute", "description": "Divides a target evenly over the people planned for picking or packing that day: the day's team target (`from.kind: team`), or one person's target (`from.kind: person`, which then loses theirs; their area stays). Each share goes onto the recipient's first area of that work, replacing its target; the remainder goes one each to the first people in name order. Recipients default to everyone planned for that work that day; only people who work in the warehouse share. Needs targets on. A day other than today needs shift planning.\n\n**Operation id:** `day_plan_targets_distribute` — the same operation is `app.day.plan_targets_distribute({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plan_targets_distribute`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "taskType": { "type": "string", "enum": [ "pick", "pack" ] }, "from": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "team" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "person" }, "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "kind", "personId" ] } ] }, "toPersonIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } }, "required": [ "warehouseId", "day", "taskType", "from" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/day-plans/from-profiles": { "post": { "operationId": "day_plans_from_profiles", "summary": "day_plans_from_profiles", "description": "Plans every empty day of up to 7 days from `startDay` with each person's usual area from their worker profile: their first floor task type, with the one zone their profile lists (pick, receive, count), their live pick profile (pick) or their home station (pack). Days that already have a plan are kept. Optionally only the listed people. Answers filled and kept.\n\n**Operation id:** `day_plans_from_profiles` — the same operation is `app.day.plans_from_profiles({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plans_from_profiles`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "startDay": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 1, "maximum": 7 }, "personIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } }, "required": [ "warehouseId", "startDay", "days" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/day-plans/set": { "post": { "operationId": "day_plan_set", "summary": "day_plan_set", "description": "Sets one person's plan for one warehouse day: up to 4 areas in order (pick, pack, receive, count or move; a zone on pick, receive, count and move, a station on pack, a pick profile on pick — Enhanced, a target on pick (orders) and pack (parcels) while targets are on — Elevate). An empty list clears the day. Pass the revision you read (null when there was no plan); a stale one is refused with revision_mismatch. Refused while day plans are off (day_plans_off), for a warehouse without a time zone (time_zone_required), outside today to 28 days ahead, for a person who does not work in the warehouse or is deactivated (person_deactivated), and for a place not live in the warehouse. Never refused for what the person may do: such an area is kept and flagged in day_plans_grid. A day other than today needs shift planning; today also assign work. `holding` names the pick batches a person moved today still holds (they stay theirs). Writes nothing when the plan is unchanged.\n\n**Operation id:** `day_plan_set` — the same operation is `app.day.plan_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plan_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "areas": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "taskType": { "type": "string", "enum": [ "pick", "pack", "receive", "count", "move" ] }, "zoneId": { "type": "string", "description": "A zones id, e.g. \"zones_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "stationId": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "pickProfileId": { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "target": { "type": "integer", "minimum": 1, "maximum": 9999 } }, "required": [ "taskType" ] } }, "expectedRevision": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "warehouseId", "personId", "day", "areas", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/team-targets/set": { "post": { "operationId": "team_day_target_set", "summary": "team_day_target_set", "description": "Sets or clears (null) the team target of one warehouse day for picking (orders: the fulfillment orders of completed customer batches) or packing (parcels). Team figures only; the wallboard shows the team's progress against it. Pass the revision you read (null when the day had none).\n\n**Operation id:** `team_day_target_set` — the same operation is `app.team.day_target_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/team_day_target_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "taskType": { "type": "string", "enum": [ "pick", "pack" ] }, "target": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9999 }, { "type": "null" } ] }, "expectedRevision": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "warehouseId", "day", "taskType", "target", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/labour/workload": { "get": { "operationId": "day_plans_workload", "summary": "day_plans_workload", "description": "The known work of a warehouse's planner days (7 or 14 from `startDay`): per day the orders known to need packing — today's open work (orders ready to pick plus parcels still to pack), a future day's open dated orders whose pack day it is (while delivery dates are on), else the parcels packed on the same weekday last week — and the receipts expected that day; plus the team's typical minutes per order picked and per parcel packed over the last 28 days (null when fewer than two people did the work). Nothing is forecast; `computedAtMs` states the answer's age. No person data.\n\n**Operation id:** `day_plans_workload` — the same operation is `app.day.plans_workload({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/day_plans_workload`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `analytics`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "labour" ], "x-operation-kind": "query", "x-min-plan": "elevate", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "startDay", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "days", "in": "query", "required": true, "schema": { "type": "number", "enum": [ 7, 14 ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-items": { "get": { "operationId": "local_items_list", "summary": "local_items_list", "description": "The LOCAL catalog (M16 W5b-F, contracts 1.4.0): goods Floormode stocks that do not exist on Shopify — Assemblified virtual raw materials (VMAT-), Assemblified sub-assemblies (ASM-) and Logistified custom items (CSTM-). Each row carries the source app, the onboarding state and the units currently held. ⚠️ These items are NOT on Shopify and are never pushed there; any surface that renders them must say so. `state` is the gate every physical flow reads: `catalog_unconfirmed` is a placeholder nothing may happen to yet, `active` is live, `archived` may be drained but not restocked, and `disconnected_frozen` is history left by a handback. RETIRED ROWS: a row that is `archived` and holds NO stock is hidden by default and returned only with `includeRetired: true` (or by asking for `state: \"archived\"` explicitly); `hiddenRetired` says how many this page dropped. A retired row that still HOLDS units is always returned, flagged `retiredWithStock`, and carries `twin` — the canonical row (same source, same published SKU, live) its stock can be swept onto with local_items_move_stock_to_twin. Archiving never detaches stock, so retired-with-stock is a work item and never hidden.\n\n**Operation id:** `local_items_list` — the same operation is `app.local.items_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_items_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-items" ], "x-operation-kind": "query", "parameters": [ { "name": "peer", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "logistified", "assemblified", "alertified" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "catalog_unconfirmed", "active", "archived", "disconnected_frozen" ] } }, { "name": "includeRetired", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-items/move-stock-to-twin": { "post": { "operationId": "local_items_move_stock_to_twin", "summary": "local_items_move_stock_to_twin", "description": "Move a RETIRED local item's remaining stock onto its canonical twin (M16 Run 3d) — the repair for a peer that minted a second id for a good it had already published. SIDE EFFECTS: posts TWO `move` stock movements per occupied bin (out of the retired item, into the SAME bin under the twin) under one `adjustment` reference and `referenceType` local_item_twin_move, resolves any open unplaced claim on the retired row, and mirrors BOTH items to the owning peer. REFUSALS (all coded in `details.localRefusal`): `item_not_retired` — the source row is not archived; `not_a_twin` — the two rows are not the same source with the same published SKU, or the target is not live; `twin_unplaced` — the target still owes an opening quantity, and moving units onto it would have them counted twice; `reserved_units` — the source holds reservations that belong to allocations pointing at it; `nothing_to_move` — the source is empty; `lot_expiry` — a lot number the source holds already exists on the twin with another expiry. Lotted units land under the same lot number and expiry on the twin. More than 100 occupied bin/lot rows answer `complete: false`: the rest, and any open claim, stay on the retired row — call again to continue. ⚠️ This is deliberately a MERCHANT action and never a sweep: a SKU is a label, not an identity, and folding two ledger positions together on a string match would delete inventory to tidy a screen.\n\n**Operation id:** `local_items_move_stock_to_twin` — the same operation is `app.local.items_move_stock_to_twin({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_items_move_stock_to_twin`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-items" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "toVariantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "variantId", "toVariantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-items/place-opening": { "post": { "operationId": "local_items_place_opening", "summary": "local_items_place_opening", "description": "Place a local item's opening quantity into a bin (M16 W5b-F) — the first-install flow, for goods that are not on Shopify. SIDE EFFECTS: posts an `import` stock movement into the named bin, closes the item's unplaced claim, marks the item onboarded, and sends the owning peer an absolute local_inventory_snapshot mirror. A quantity above zero REQUIRES a destination (binId, or binCode with warehouseId) — a local item's units may never be placed without a location. `qty: 0` is a legitimate answer meaning 'I looked, there are none': it closes the claim and posts no movement, which is how a zero-stock item is activated by hand. An item may be placed ONCE — a second call is refused with localRefusal `item_already_placed`, because a second `import` would leave the shop holding its opening quantity twice; change a placed item's stock with a receipt, a count or an adjustment instead. `lots` places part or all of `qty` under named lots (an existing lot keeps its date; a lot-tracked item may create one), the rest without a lot. When the item came back in lots (`suggestedLots` on local_items_unplaced), every unit beyond `suggestedUnlotted` needs its lot, else the call is refused with code `lot_required`.\n\n**Operation id:** `local_items_place_opening` — the same operation is `app.local.items_place_opening({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_items_place_opening`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-items" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "binId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "binCode": { "type": "string", "minLength": 1 }, "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lots": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "lotNumber": { "type": "string", "minLength": 1, "maxLength": 64 }, "expiryDate": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "lotNumber", "qty" ] } } }, "required": [ "variantId", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-items/unplaced": { "get": { "operationId": "local_items_unplaced", "summary": "local_items_unplaced", "description": "The UNPLACED worklist (M16 W5b-F): local items whose opening quantity has never been placed into a bin. ⚠️ These are CLAIMS, not inventory — they contribute ZERO to bins, ATP, counts, supply outlook and planning, and no physical flow may act on an item while its claim is open (a pick answers the coded refusal `item_unplaced`). `sourceQuantity` is null whenever the source app stated none, which under contracts 1.4.0 is always: no peer→Floormode quantity channel exists, so the merchant counts the shelf. `suggestedLots` names the lots (number, date, quantity) an item came back in when a reconnect reopened its claim, and `suggestedUnlotted` its units that had no lot. Clear a row with local_items_place_opening.\n\n**Operation id:** `local_items_unplaced` — the same operation is `app.local.items_unplaced({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_items_unplaced`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-items" ], "x-operation-kind": "query", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-stock/disconnect": { "post": { "operationId": "local_stock_begin_disconnect", "summary": "local_stock_begin_disconnect", "description": "Begin handing a peer's local stock back (M16 W5b-F) — phase one of a two-phase disconnect. ⚠️ SIDE EFFECTS, and they are not reversible by a second call: the peer's open component pick batches are CANCELLED first (picked units go back to their bins), the peer's local stock is FROZEN (no receipts, picks, counts or adjustments), an absolute cutover snapshot is derived from the ledger and queued to the peer, and the connection stays in `disconnecting` until the peer acknowledges the exact digest. A failed or absent acknowledgement leaves it there, which is the safe state — nobody is writing twice. Only after the acknowledgement do Floormode's rows become frozen history, which is what lets a reconnect place the DIFFERENCE rather than both totals.\n\n**Operation id:** `local_stock_begin_disconnect` — the same operation is `app.local.stock_begin_disconnect({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_stock_begin_disconnect`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-stock" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peer": { "type": "string", "enum": [ "logistified", "assemblified", "alertified" ] } }, "required": [ "peer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/local-stock/status": { "get": { "operationId": "local_stock_status", "summary": "local_stock_status", "description": "Local-stock ownership state per peer (M16 W5b-F): the lifecycle phase (`inactive`, `active`, `disconnecting`, `released`), how many local items are held, how many are still unconfirmed placeholders, how many are frozen history, and the in-flight disconnect handback with its digest and acknowledgement. Plus the shop-wide count of unplaced claims. Read-only; this is what the Settings → Integrations panel shows.\n\n**Operation id:** `local_stock_status` — the same operation is `app.local.stock_status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/local_stock_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "local-stock" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/location-types": { "get": { "operationId": "location_types_list", "summary": "location_types_list", "description": "List the tenant's location types (bin, pallet, floor, staging, dock, hospital, work_area, transfer) with their storable flag, pickable/sellable defaults, capacity mode and default packing efficiency. Before the first use the standard set is returned.\n\n**Operation id:** `location_types_list` — the same operation is `app.location.types_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/location_types_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "location-types" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "location_types_upsert", "summary": "location_types_upsert", "description": "Update one location type by key (seeding the standard set on first use). Only the fields you pass change; defaultPackingEfficiency must be a fraction in (0, 1].\n\n**Operation id:** `location_types_upsert` — the same operation is `app.location.types_upsert({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/location_types_upsert`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "location-types" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "bin", "pallet", "floor", "staging", "dock", "hospital", "work_area", "transfer" ] }, "label": { "type": "string", "minLength": 1 }, "storable": { "type": "boolean" }, "pickableDefault": { "type": "boolean" }, "sellableDefault": { "type": "boolean" }, "capacityMode": { "type": "string", "enum": [ "units", "weight", "cube", "pallets", "footprint", "none" ] }, "defaultPackingEfficiency": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations": { "post": { "operationId": "locations_create", "summary": "locations_create", "description": "Create a location node in the tree. Optionally nest it under parentId (same warehouse), set its nodeKind (zone/aisle/bay/level/leaf), locationTypeId and mix rules. depth and the materialized path are computed from the parent chain; the code is uppercased and must be unique in the warehouse. Optional canvas placement is committed atomically with the location; it does not set travel coordinates or stock.\n\n**Operation id:** `locations_create` — the same operation is `app.locations.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "code": { "type": "string", "minLength": 1 }, "canvas": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0 }, "y": { "type": "number", "minimum": 0 }, "w": { "type": "number", "exclusiveMinimum": 0 }, "h": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "x", "y", "w", "h" ] }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "parentId": { "description": "document id of the parent node.", "type": "string", "format": "floormode-id" }, "nodeKind": { "type": "string", "enum": [ "zone", "aisle", "bay", "level", "leaf" ] }, "locationTypeId": { "description": "document id of a location type.", "type": "string", "format": "floormode-id" }, "binType": { "description": "Underlying bin type; defaults to pick.", "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "barcode": { "type": "string" }, "pickable": { "type": "boolean" }, "sellable": { "type": "boolean" }, "shopifyInventoryState": { "anyOf": [ { "type": "string", "enum": [ "available", "damaged", "reserved", "quality_control", "safety_stock" ] }, { "type": "null" } ] }, "singleSkuOnly": { "type": "boolean" }, "singleLotOnly": { "type": "boolean" } }, "required": [ "warehouseId", "code" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/apply-template": { "post": { "operationId": "locations_apply_template", "summary": "locations_apply_template", "description": "Instantiate an app-provided layout template (flat, shelving, pallet_racking, bulk_floor, threePL_full) into a warehouse using the grid generator. `params` may override per-axis counts (by token), the formula, the leaf location type key, the zone and mix rules, and nest the result under params.parentId. Templates are combinable — applying one to a warehouse that already has a subtree just adds nodes (existing codes are skipped).\n\n**Operation id:** `locations_apply_template` — the same operation is `app.locations.apply_template({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_apply_template`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "templateKey": { "type": "string", "enum": [ "flat", "shelving", "pallet_racking", "bulk_floor", "threePL_full" ] }, "params": { "type": "object", "properties": { "parentId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "formula": { "type": "string" }, "counts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "intermediateNodes": { "type": "boolean" }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leafLocationTypeKey": { "type": "string", "enum": [ "bin", "pallet", "floor", "staging", "dock", "hospital", "work_area", "transfer" ] }, "binType": { "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] }, "singleSkuOnly": { "type": "boolean" }, "singleLotOnly": { "type": "boolean" } } } }, "required": [ "warehouseId", "templateKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/capacity": { "get": { "operationId": "locations_capacity", "summary": "locations_capacity", "description": "Capacity and current fill of one location (M9 T3, WHT-005). A leaf reports its own fill; an interior node reports the bounded roll-up of its subtree leaves. `fillRate` (0..1+, MAX across the units/weight/cube constraints present) and `level` (empty/low/normal/high/full/unbounded) drive fill badges and the map; both are null/unbounded when the location declares no capacity — exactly today's flat bin.\n\n**Operation id:** `locations_capacity` — the same operation is `app.locations.capacity({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_capacity`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "parameters": [ { "name": "locationId", "in": "query", "required": true, "description": "document id of the location (bin) node.", "schema": { "type": "string", "description": "document id of the location (bin) node.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/capacity-summary": { "get": { "operationId": "locations_capacity_summary", "summary": "locations_capacity_summary", "description": "Capacity fill for every direct child of one tree level in one read — the layout editor's heatmap source. Pass parentId for a node's children or warehouseId for the roots.\n\n**Operation id:** `locations_capacity_summary` — the same operation is `app.locations.capacity_summary({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_capacity_summary`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "parameters": [ { "name": "parentId", "in": "query", "required": false, "description": "Direct children of this node.", "schema": { "description": "Direct children of this node.", "type": "string", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Roots of this warehouse.", "schema": { "description": "Roots of this warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/capacity/bulk": { "post": { "operationId": "locations_capacity_bulk", "summary": "locations_capacity_bulk", "description": "The capacity report of up to 200 locations in one read — the same shape `locations_capacity` answers per node, keyed by id. Unknown ids are skipped.\n\n**Operation id:** `locations_capacity_bulk` — the same operation is `app.locations.capacity_bulk({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_capacity_bulk`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "document ids of the locations." } }, "required": [ "locationIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/generate-grid": { "post": { "operationId": "locations_generate_grid", "summary": "locations_generate_grid", "description": "Bulk-generate a location subtree from a grid spec (Ongoing-style). `spec` = ordered axes (each with a token, count, optional start/style/pad/nodeKind) plus a naming formula that references every axis token once in order, e.g. \"A-{bay}-{level}-{pos}\". With intermediateNodes it also creates the interior zone/aisle/bay/level nodes; otherwise it creates flat leaves under parentId. Idempotent — existing codes are skipped (reported as `skipped`), the rest created in one bounded transaction (cap 2000 nodes). Interior nodes are non-pickable/non-sellable.\n\n**Operation id:** `locations_generate_grid` — the same operation is `app.locations.generate_grid({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_generate_grid`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "parentId": { "description": "document id of the parent node the grid hangs under.", "type": "string", "format": "floormode-id" }, "spec": { "type": "object", "properties": { "formula": { "type": "string", "minLength": 1, "description": "Leaf naming formula, e.g. \"A-{bay}-{level}-{pos}\"." }, "axes": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Formula token this axis fills." }, "count": { "type": "integer", "minimum": 1, "maximum": 1000 }, "start": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "style": { "type": "string", "enum": [ "number", "alpha" ] }, "pad": { "type": "integer", "minimum": 0, "maximum": 8 }, "nodeKind": { "type": "string", "enum": [ "zone", "aisle", "bay", "level", "leaf" ] } }, "required": [ "token", "count" ] } }, "intermediateNodes": { "type": "boolean" } }, "required": [ "formula", "axes" ] }, "leafLocationTypeId": { "description": "document id of the leaf location type.", "type": "string", "format": "floormode-id" }, "leafLocationTypeKey": { "type": "string", "enum": [ "bin", "pallet", "floor", "staging", "dock", "hospital", "work_area", "transfer" ] }, "binType": { "description": "Underlying bin type for the leaves; defaults to pick.", "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "singleSkuOnly": { "type": "boolean" }, "singleLotOnly": { "type": "boolean" }, "capacity": { "description": "Default capacity columns seeded onto every generated leaf (WHT-005).", "type": "object", "properties": { "maxUnits": { "type": "number", "minimum": 0 }, "maxWeightG": { "type": "number", "minimum": 0 }, "maxLengthMm": { "type": "number", "minimum": 0 }, "maxWidthMm": { "type": "number", "minimum": 0 }, "maxHeightMm": { "type": "number", "minimum": 0 }, "maxPallets": { "type": "number", "minimum": 0 }, "packingEfficiency": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } } } }, "required": [ "warehouseId", "spec" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/get": { "get": { "operationId": "locations_get", "summary": "locations_get", "description": "Get one location node with its parent, its direct children and the child count.\n\n**Operation id:** `locations_get` — the same operation is `app.locations.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "parameters": [ { "name": "locationId", "in": "query", "required": true, "description": "document id of the location (bin) node.", "schema": { "type": "string", "description": "document id of the location (bin) node.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/move": { "post": { "operationId": "locations_move", "summary": "locations_move", "description": "Reparent a location node (newParentId null makes it top-level). Recomputes depth and the materialized path for the whole moved subtree in one bounded transaction; moving a node under its own descendant is rejected (cycle guard).\n\n**Operation id:** `locations_move` — the same operation is `app.locations.move({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_move`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "newParentId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ], "description": "document id of the new parent, or null." } }, "required": [ "locationId", "newParentId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/recompute-serpentine": { "post": { "operationId": "locations_recompute_serpentine", "summary": "locations_recompute_serpentine", "description": "Recompute the composite serpentine pick sequence (M10 T1, WHT-008) for a warehouse's pickable stock-holding leaves. Rewrites each leaf's pickSequence from its structured position (zone → aisle → serpentine-side → bay) so a route snakes (S-shape) instead of sorting alphabetically — the highest-ROI routing step, no map required. Additive and idempotent: only changed leaves are patched, a second run is a no-op, and interior/staging/non-pickable bins keep their sequence. Returns the leaf count and how many sequences changed.\n\n**Operation id:** `locations_recompute_serpentine` — the same operation is `app.locations.recompute_serpentine({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_recompute_serpentine`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/reorder": { "post": { "operationId": "locations_reorder", "summary": "locations_reorder", "description": "Place a location in a level and position: reparent it (newParentId null = top level) and land it before `beforeId`, or last in that level. The warehouse's pick route is renumbered to follow the tree; refused above 2,000 active locations.\n\n**Operation id:** `locations_reorder` — the same operation is `app.locations.reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "newParentId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ], "description": "document id of the level's container, or null." }, "beforeId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ], "description": "sibling it lands before, or null for last." } }, "required": [ "locationId", "newParentId", "beforeId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/search": { "get": { "operationId": "locations_search", "summary": "locations_search", "description": "Search all warehouse levels by code prefix. Each result includes its full location path; cursor continues after the last result.\n\n**Operation id:** `locations_search` — the same operation is `app.locations.search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "search", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/set-geometry": { "post": { "operationId": "locations_set_geometry", "summary": "locations_set_geometry", "description": "Persist a location's 2D map geometry (M9 T4, WHT-007). `canvas` sets the rectangle drawn on the map (x/y top-left, w/h size, rotation, color); `coords` sets the logical travel coordinates x/y/z (X/Y horizontal, Z the vertical rack level, consumed by M10 routing). Every field is independently optional — null clears a column, omitting it leaves it. The map is a purely additive visual layer, so this never affects allocation or picking.\n\n**Operation id:** `locations_set_geometry` — the same operation is `app.locations.set_geometry({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_set_geometry`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "description": "document id of the location (bin) node.", "format": "floormode-id" }, "canvas": { "type": "object", "properties": { "x": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "y": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "w": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "h": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "rotation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "coords": { "type": "object", "properties": { "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "z": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "required": [ "locationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/set-geometry-bulk": { "post": { "operationId": "locations_set_geometry_bulk", "summary": "locations_set_geometry_bulk", "description": "Persist canvas geometry for up to 300 locations in one call (layout editor batch save): one transaction, one invalidation. Fails closed — an unknown location id writes nothing. Requires each location’s complete expectedCanvas snapshot; stale geometry refuses the entire batch.\n\n**Operation id:** `locations_set_geometry_bulk` — the same operation is `app.locations.set_geometry_bulk({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_set_geometry_bulk`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 300, "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "string", "description": "document id of the location (bin) node.", "format": "floormode-id" }, "expectedCanvas": { "type": "object", "properties": { "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "w": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "h": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rotation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "x", "y", "w", "h", "rotation", "color" ] }, "canvas": { "type": "object", "properties": { "x": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "y": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "w": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "h": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "rotation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "description": "null or blank clears the override.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "required": [ "locationId", "expectedCanvas", "canvas" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/tree": { "get": { "operationId": "locations_tree", "summary": "locations_tree", "description": "Read a bounded slice of the hierarchical location tree. Pass pathPrefix WITH warehouseId for a whole subtree (the node at that path and its descendants; paths are unique per warehouse), parentId for the direct children of a node, or warehouseId alone for the top-level nodes. `capped` flags a truncated result.\n\n**Operation id:** `locations_tree` — the same operation is `app.locations.tree({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_tree`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "query", "parameters": [ { "name": "storeyId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "parentId", "in": "query", "required": false, "description": "document id of the parent node.", "schema": { "description": "document id of the parent node.", "type": "string", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "pathPrefix", "in": "query", "required": false, "description": "Materialized path of the subtree root, e.g. \"A/A-01\" (needs warehouseId).", "schema": { "description": "Materialized path of the subtree root, e.g. \"A/A-01\" (needs warehouseId).", "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/locations/update": { "post": { "operationId": "locations_update", "summary": "locations_update", "description": "Update the type attributes of a location node: locationTypeId (null clears), the mix rules singleSkuOnly/singleLotOnly (null clears), zone, the pickable/sellable flags and the volumetric capacity columns (maxUnits, maxWeightG, maxLengthMm/WidthMm/HeightMm, maxPallets, packingEfficiency — null clears a column, packingEfficiency is a fraction in (0,1]). nodeKind is derived by the tree writer (a node with children is never a leaf) and cannot be set here. Use locations_move to reparent and bins_update for the code.\n\n**Operation id:** `locations_update` — the same operation is `app.locations.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/locations_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "locations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "locationTypeId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "singleSkuOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "dedicatedProductId": { "description": "\"Only this product\": placements of other products refuse; null clears.", "anyOf": [ { "type": "string", "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "singleLotOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pickable": { "type": "boolean" }, "sellable": { "type": "boolean" }, "shopifyInventoryState": { "anyOf": [ { "type": "string", "enum": [ "available", "damaged", "reserved", "quality_control", "safety_stock" ] }, { "type": "null" } ] }, "maxUnits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxWeightG": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxLengthMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxWidthMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxHeightMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxVolumeCm3": { "description": "Explicit usable volume in cm³; wins over L×W×H, no packing factor.", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxPallets": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "packingEfficiency": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "locationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots": { "get": { "operationId": "lots_list", "summary": "lots_list", "description": "List lots by lot number, 50 a page (the answer is { rows, capped, cursor } — pass `cursor` back to continue). `search` is the start of a lot number (any case), `variantId` one item's lots, `sort` lot:asc or lot:desc. Each row: the lot number, its date (expiryDate, an ISO day or null) and status, the item (sku, title, what the date means) and the units on hand across every bin.\n\n**Operation id:** `lots_list` — the same operation is `app.lots.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "The start of a lot number, any case (lot numbers are stored upper case).", "schema": { "description": "The start of a lot number, any case (lot numbers are stored upper case).", "type": "string", "maxLength": 64 } }, { "name": "variantId", "in": "query", "required": false, "description": "Only this item's lots.", "schema": { "description": "Only this item's lots.", "type": "string", "format": "floormode-id" } }, { "name": "sort", "in": "query", "required": false, "description": "`lot:asc` (the default) or `lot:desc`: by lot number.", "schema": { "description": "`lot:asc` (the default) or `lot:desc`: by lot number.", "type": "string", "enum": [ "lot:asc", "lot:desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/archived-inbound": { "get": { "operationId": "history_lot_inbound", "summary": "history_lot_inbound", "description": "A lot's receipts and returns that left Floormode for the history archive two years after their day (the lot's inbound book): newest first, up to 200 a page, each with its instant, units, warehouse and document — for a receipt its purchase order's number and supplier. beforeMs is where lots_get's received and returned rows begin; a row on both sides is the same movement.\n\n**Operation id:** `history_lot_inbound` — the same operation is `app.history.lot_inbound({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_lot_inbound`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "lotId", "in": "query", "required": true, "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/archived-trace": { "get": { "operationId": "history_lot_ships", "summary": "history_lot_ships", "description": "A lot's shipments that left Floormode for the history archive (the lot book): newest first, up to 200 a page, each with its instant, units, warehouse, document and order (Shopify id and name; null once deleted). beforeMs is where lots_trace's own pages begin; the two never overlap.\n\n**Operation id:** `history_lot_ships` — the same operation is `app.history.lot_ships({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_lot_ships`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "lotId", "in": "query", "required": true, "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/block": { "post": { "operationId": "lots_block", "summary": "lots_block", "description": "Block a lot: from now nothing of it is allocated, picked or sold. Its reservations are re-planned onto another lot of the item, or the order goes short; warehouses whose Shopify number Floormode sets from its stock (legacy) re-push their availability; a local item's levels are re-mirrored to its owner. A live warehouse (causal pairs) moves the lot's free units on sellable shelves from Shopify's available to quality_control at once, and every unit the re-plan frees after them; an order left short keeps its Shopify commitment, so Shopify's available goes below zero for it. Quarantine (lots_quarantine) then only clears the shelves: Shopify's numbers stay as they are. Units already on the floor are refused at pick (lot_blocked: report the line short); a parcel holding them is declined at packing_fulfill until packing_release_blocked_units puts them aside. reason: recall, quality_hold, supplier_notice or other; note up to 500 characters. Raises a lot_blocked alert and the lot.blocked event. Answers { replanned, ordersShort, pushed, pending (a background pass finishes a large lot), toQuarantine (per warehouse, units and bins still on sellable shelves) }. A blocked lot is refused as illegal_transition.\n\n**Operation id:** `lots_block` — the same operation is `app.lots.block({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_block`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotId": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" }, "reason": { "type": "string", "enum": [ "recall", "quality_hold", "supplier_notice", "other" ], "description": "Why: recall, quality_hold, supplier_notice or other." }, "note": { "description": "Shown on the lot and in its alert.", "type": "string", "maxLength": 500 }, "cascade": { "description": "Also block the hamper batches made from this lot that still hold stock (default false).", "type": "boolean" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "lotId", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/by-order": { "get": { "operationId": "lots_for_order", "summary": "lots_for_order", "description": "The lots one order shipped: per lot its number, date, item and the units, from the order's pack jobs and fulfilments. capped when the order has more documents than one read walks.\n\n**Operation id:** `lots_for_order` — the same operation is `app.lots.for_order({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_for_order`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "orderId", "in": "query", "required": true, "description": "document id of the order.", "schema": { "type": "string", "description": "document id of the order.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/detail": { "get": { "operationId": "lots_get", "summary": "lots_get", "description": "Read one lot: the lot and its item; counts — on hand (units, bins, warehouses), reserved, shipped to orders (units, shipment lines, distinct orders — a lower bound over the newest 5,000 lines when ordersCapped — and the last ship) and returned; where it is now (bins, stockCapped) and the receipts it came in on (received, receivedCapped). hotFromMs is where its shipment history starts in Floormode; archive is null while none can be older. Null for an unknown lot. The shipments themselves: lots_trace.\n\n**Operation id:** `lots_get` — the same operation is `app.lots.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "lotId", "in": "query", "required": true, "description": "document id of the lot.", "schema": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/exports": { "get": { "operationId": "lots_export_get", "summary": "lots_export_get", "description": "A lot's newest affected-orders export, or null: status (queued, running, done, failed), columns, sinceMs, rowsWritten, partial (what the file lacks, in words) or failureReason, and while its file is kept fileBytes and availableUntilMs.\n\n**Operation id:** `lots_export_get` — the same operation is `app.lots.export_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_export_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "lotId", "in": "query", "required": true, "description": "document id of the lot.", "schema": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "lots_export_start", "summary": "lots_export_start", "description": "Export a lot's affected orders as a CSV file — one row per shipment, every shipment (archived ones too) or those since sinceMs — with the columns you pick: order, shipped (UTC day), units, store, and the customer's name, email, phone, country and shipping address, read from Shopify as the file is written (an erased customer reads redacted, a field the app may not read withheld). Runs in the background; answers { exportId }. One export per lot at a time: another is refused as lot_export_running with the open exportId. Follow it with lots_export_get; the file is downloaded from GET /api/lots/exports/{exportId} for 7 days.\n\n**Operation id:** `lots_export_start` — the same operation is `app.lots.export_start({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_export_start`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotId": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" }, "sinceMs": { "description": "Only shipments at or after this instant (milliseconds since 1970, UTC); absent or null for every shipment.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "columns": { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "order", "shipped", "units", "store", "name", "email", "phone", "country", "address" ] }, "description": "Columns to write, in any order: order, shipped, units, store, name, email, phone, country, address. Customer columns are read from Shopify, never stored." }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "lotId", "columns" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/quarantine": { "post": { "operationId": "lots_quarantine", "summary": "lots_quarantine", "description": "Move a blocked or expired lot to quarantine in one warehouse: one floor move task per sellable bin holding free units of it, from that bin to QUAR-01 (an unstarted task of the same bin is topped up instead). Each completed move of an expired lot takes the units out of Shopify's available into quality control; a blocked lot's left it at the block. Reserved units stay with their orders. Answers { tasksCreated, tasksToppedUp, units, binsCapped }.\n\n**Operation id:** `lots_quarantine` — the same operation is `app.lots.quarantine({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_quarantine`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotId": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" }, "warehouseId": { "type": "string", "description": "The warehouse whose sellable bins hold the lot's units.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "lotId", "warehouseId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/trace": { "get": { "operationId": "lots_trace", "summary": "lots_trace", "description": "Who got a lot: its shipments to orders, newest first, 50 a page ({ rows, capped, cursor }). Each row: when it shipped, the units, the warehouse, the document that shipped it (pack_job, pick_line or allocation_line, with its id) and the order (orderId, shopifyOrderId, orderName, channelKey — null when the order was deleted). No customer data: read the order for that. A cursor from before the lot's history moved to the archive is refused as stale_cursor; start again.\n\n**Operation id:** `lots_trace` — the same operation is `app.lots.trace({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_trace`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "query", "parameters": [ { "name": "lotId", "in": "query", "required": true, "description": "document id of the lot.", "schema": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" } }, { "name": "atFromMs", "in": "query", "required": false, "description": "Shipments at or after this instant (milliseconds since 1970, UTC).", "schema": { "description": "Shipments at or after this instant (milliseconds since 1970, UTC).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "sort", "in": "query", "required": false, "description": "`at:desc`, newest first (the only order).", "schema": { "description": "`at:desc`, newest first (the only order).", "type": "string", "enum": [ "at:desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lots/unblock": { "post": { "operationId": "lots_unblock", "summary": "lots_unblock", "description": "Unblock a lot: it is allocated, picked and sold again, and the orders that went short for want of it are re-planned. A live warehouse moves the lot's free units on sellable shelves back to Shopify's available. Its open quarantine tasks are cancelled; units already moved to QUAR-01 stay there until moved back. The last block's reason and note stay on the lot. Raises the lot.unblocked event. Answers like lots_block; a lot that is not blocked is refused as illegal_transition.\n\n**Operation id:** `lots_unblock` — the same operation is `app.lots.unblock({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/lots_unblock`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "lots" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotId": { "type": "string", "description": "document id of the lot.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "lotId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/manifests": { "get": { "operationId": "manifests_list", "summary": "manifests_list", "description": "List end-of-day manifests, newest first (max 100), with the warehouse and carrier label and `shipmentCount`, the exact number of shipments each covers (`shipmentIds` lists at most 100 of them). Filter by status (open, closed, cancelled), warehouse or carrier account.\n\n**Operation id:** `manifests_list` — the same operation is `app.manifests.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/manifests_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "manifests" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "closing", "open", "closed", "cancelled" ] } }, { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "carrierAccountId", "in": "query", "required": false, "description": "document id of the carrier account.", "schema": { "description": "document id of the carrier account.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/manifests/resolve": { "post": { "operationId": "manifests_resolveCloseOut", "summary": "manifests_resolveCloseOut", "description": "Resolve an outstanding carrier close-out whose acceptance nobody could read: `announced` records the manifest on the operator's attestation (with the carrier's confirmation number when known), `not_announced` frees its parcels for another close-out. Refused while the attempt is still running, and `not_announced` is refused when the carrier's answer is held.\n\n**Operation id:** `manifests_resolveCloseOut` — the same operation is `app.manifests.resolveCloseOut({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/manifests_resolveCloseOut`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "manifests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manifestId": { "type": "string", "description": "A manifests id, e.g. \"manifests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "verdict": { "type": "string", "enum": [ "announced", "not_announced" ] }, "confirmationNumber": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "manifestId", "verdict" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notes": { "get": { "operationId": "notes_list", "summary": "notes_list", "description": "List the newest notes of the authenticated tenant (max 100).\n\n**Operation id:** `notes_list` — the same operation is `app.notes.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notes_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notes" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "notes_create", "summary": "notes_create", "description": "Create a note for the authenticated tenant. Body must be 1-500 characters.\n\n**Operation id:** `notes_create` — the same operation is `app.notes.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notes_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notes" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The note text." } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications": { "get": { "operationId": "notifications_log", "summary": "notifications_log", "description": "List WISMO customer notifications (OMS-076), newest first, as a disclosed page (`rows`/`capped`, max 100). Each row has the order, channel, milestone, status (pending, sending, sent, failed, no_provider, expired), recipient, any provider message id and the last `error` — the reason a failed send died. Filter by status; `failed`/`no_provider`/`expired` rows can be re-queued with notifications_retry.\n\n**Operation id:** `notifications_log` — the same operation is `app.notifications.log({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_log`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "no_provider", "expired" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/order-owner": { "get": { "operationId": "notifications_order_owner", "summary": "notifications_order_owner", "description": "Read the immutable shipment-email owner for an order. Null means the first fulfillment or email submission has not claimed an owner yet. Settings changes apply only to orders without a claim.\n\n**Operation id:** `notifications_order_owner` — the same operation is `app.notifications.order_owner({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_order_owner`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "query", "parameters": [ { "name": "orderId", "in": "query", "required": true, "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/order-sent": { "get": { "operationId": "notifications_order_sent", "summary": "notifications_order_sent", "description": "The milestone e-mails Floormode sent an order's customer, and when: one row per milestone and scope (the order, a shipment, a return label), newest first, for as long as the order is in Floormode. notifications_log lists the last 7 days of sends.\n\n**Operation id:** `notifications_order_sent` — the same operation is `app.notifications.order_sent({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_order_sent`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "query", "parameters": [ { "name": "orderId", "in": "query", "required": true, "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/resume-sending": { "post": { "operationId": "notifications_resumeSending", "summary": "notifications_resumeSending", "description": "Resume customer e-mails after Floormode paused them (roadmap I-A). Floormode pauses the account's customer e-mails when, over the last seven days, bounces or spam complaints pass half of the e-mail provider's account limits, at a meaningful volume. E-mails due while paused were settled skipped and are not sent late. Answers resumed: false when nothing was paused.\n\n**Operation id:** `notifications_resumeSending` — the same operation is `app.notifications.resumeSending({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_resumeSending`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "mutation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/retry": { "post": { "operationId": "notifications_retry", "summary": "notifications_retry", "description": "Re-queue a terminal customer notification (status failed, no_provider or expired): the row goes back to pending, claimable now, and the sweep is armed in the same transaction. Any other status is a conflict (`notification_not_retryable`) — a sent row reached the customer, a pending one is already on its way.\n\n**Operation id:** `notifications_retry` — the same operation is `app.notifications.retry({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_retry`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notificationId": { "type": "string", "description": "Document id of the notification row.", "format": "floormode-id" } }, "required": [ "notificationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/settings": { "get": { "operationId": "notifications_settings_get", "summary": "notifications_settings_get", "description": "Get the WISMO customer-notification settings (OMS-076): the master enable + customer opt-in, which tracking milestones notify (pre_transit, in_transit, out_for_delivery, delivered, exception, failed_attempt, return_to_sender), the sender name and the branded tracking-page theming (store name, logo, accent colour, title, help text and layout).\n\n**Operation id:** `notifications_settings_get` — the same operation is `app.notifications.settings_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_settings_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "notifications_settings_update", "summary": "notifications_settings_update", "description": "Update the WISMO notification settings (OMS-076): who sends and which milestones. Pass expectedRevision from the latest settings read (null for unstored defaults); stale writes are refused. Pass only the fields to change; milestones are merged into the current config. The e-mails' look, words and sender are customerPages_brand_save's. Milestones come in two families: the seven carrier tracking statuses (on by default except return_to_sender), and the three pre-shipment ORDER milestones — order_held (a delay notice, sent only for the awaiting_stock / awaiting_production / awaiting_supplier hold reasons, never for fraud, payment or address holds), backordered (an allocation went short) and partially_shipped (some of the order shipped, the rest is coming). All three default to OFF and are sent at most once per order.\n\n**Operation id:** `notifications_settings_update` — the same operation is `app.notifications.settings_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/notifications_settings_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "notifications" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownershipMode": { "type": "string", "enum": [ "shopify", "floormode", "none", "legacy" ] }, "enabled": { "type": "boolean" }, "customerOptIn": { "type": "boolean" }, "milestones": { "type": "object", "properties": { "pre_transit": { "type": "boolean" }, "in_transit": { "type": "boolean" }, "out_for_delivery": { "type": "boolean" }, "delivered": { "type": "boolean" }, "exception": { "type": "boolean" }, "failed_attempt": { "type": "boolean" }, "return_to_sender": { "type": "boolean" }, "order_held": { "type": "boolean" }, "backordered": { "type": "boolean" }, "partially_shipped": { "type": "boolean" }, "shipment_confirmed": { "type": "boolean" }, "return_label_ready": { "type": "boolean" } } }, "expectedRevision": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders": { "get": { "operationId": "orders_list", "summary": "orders_list", "description": "List mirrored Shopify orders of the authenticated tenant, newest first (50 per page). Optionally filter by fulfillment status and paginate with the returned cursor. Each row carries both identifiers — `_id` (this app's order document id) and `shopifyOrderId` — and orders_get accepts either, so the list→detail chain works with whichever one you already hold. `historyFromMs`: orders last updated before it may be in the history archive.\n\n**Operation id:** `orders_list` — the same operation is `app.orders.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Fulfillment status filter, e.g. \"unfulfilled\" or \"fulfilled\".", "schema": { "description": "Fulfillment status filter, e.g. \"unfulfilled\" or \"fulfilled\".", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor: the `cursor` value returned by the previous page.", "schema": { "description": "Pagination cursor: the `cursor` value returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/actions/reconcile": { "post": { "operationId": "orders_action_reconcile", "summary": "orders_action_reconcile", "description": "Ask Shopify again what became of an order request (OMS-1). An unresolved request gets one read-only check (an open check is answered instead of doubled); a request Shopify confirmed whose order has not caught up gets a fresh order refresh. Works after the original queue rows were pruned. The same requestKey replays the first answer.\n\n**Operation id:** `orders_action_reconcile` — the same operation is `app.orders.action_reconcile({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_action_reconcile`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "actionId": { "type": "string", "description": "The order request to check, as listed in the order's appActions.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "shopifyOrderId", "actionId", "requestKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/actions/resolve": { "post": { "operationId": "orders_action_resolve", "summary": "orders_action_resolve", "description": "Settle an order request by hand (OMS-1). abandon: the operator attests that Shopify did NOT apply an unresolved request and the order returns to the floor; refused while Shopify last reported the job still running or while a check is open, and later Shopify evidence still overrules it on the record. accept_confirmed: accept an effect Shopify confirmed before the order shows it.\n\n**Operation id:** `orders_action_resolve` — the same operation is `app.orders.action_resolve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_action_resolve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "actionId": { "type": "string", "description": "The order request to check, as listed in the order's appActions.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "resolution": { "type": "string", "enum": [ "abandon", "accept_confirmed" ], "description": "abandon: attest that Shopify did NOT apply an unresolved request (the order returns to the floor). accept_confirmed: accept an effect Shopify confirmed before the order mirror shows it." } }, "required": [ "shopifyOrderId", "actionId", "requestKey", "resolution" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/allocation-gaps": { "get": { "operationId": "orders_allocation_gaps", "summary": "orders_allocation_gaps", "description": "Explain why an order is short of stock: one row per missing item with its variant, sku, the number of units that could NOT be reserved, how many of those are accepted backorders, and the warehouse the reservation was attempted at. An order with nothing missing returns an empty list (not an error). `capped` reports whether the line read hit its ceiling. This is the detail behind the work queue's `shortSkuCount`.\n\n**Operation id:** `orders_allocation_gaps` — the same operation is `app.orders.allocation_gaps({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_allocation_gaps`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Numeric Shopify order id as a string.", "schema": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/cancel": { "post": { "operationId": "orders_cancel", "summary": "orders_cancel", "description": "Cancel an order in Shopify (OMS-1 G-05). Admitted only while nothing conflicting is in flight on the order; a refusal names its reason in details.code (for example cancel_pending, fulfillment_in_flight, capture_in_flight, open_return or dropship_open). The order's floor work and reserved stock are released at once and a merge group it is in is cancelled; Shopify's answer settles the request, and a refusal brings the work back. The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `orders_cancel` — the same operation is `app.orders.cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "reason": { "type": "string", "enum": [ "customer", "declined", "fraud", "inventory", "other", "staff" ], "description": "Why the order is cancelled: Shopify's OrderCancelReason, lower-cased." }, "restock": { "type": "boolean", "description": "Put the order's unfulfilled units back into Shopify stock." }, "refund": { "type": "boolean", "description": "Refund captured money to the original payment methods. An authorized payment that was never captured is voided either way." }, "notifyCustomer": { "type": "boolean", "description": "Send Shopify's cancellation email to the customer." }, "staffNote": { "description": "Internal note on the Shopify order; the customer never sees it.", "type": "string", "maxLength": 255 } }, "required": [ "shopifyOrderId", "requestKey", "reason", "restock", "refund", "notifyCustomer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/capture-payment": { "post": { "operationId": "orders_capture_payment", "summary": "orders_capture_payment", "description": "Capture the outstanding authorized payment of an order (OMS-074) via Shopify `orderCapture`. Only an authorized or partially-paid order can be captured; a paid order is already captured. Shopify Payments authorizations expire after ~7 days. The capture-on-fulfill warehouse toggle queues the same capture automatically at ship time.\n\n**Operation id:** `orders_capture_payment` — the same operation is `app.orders.capture_payment({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_capture_payment`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } }, "required": [ "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/customer-page": { "post": { "operationId": "customerPages_open", "summary": "customerPages_open", "description": "The order's page in its store (roadmap I-B2), as the shopper's link opens it: the store's primary domain, the store page's path and the order's capability in the fragment (#c=…). Anyone holding the URL sees the order's delivery status, items, city and country, never an address, a name or a price. url is null with reason carrier when the store links customers to the carrier's tracking page instead, and no_host while the store's primary domain is not recorded yet.\n\n**Operation id:** `customerPages_open` — the same operation is `app.customerPages.open({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/customerPages_open`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/customer-page/revoke": { "post": { "operationId": "customerPages_revoke", "summary": "customerPages_revoke", "description": "Revoke the order's customer page link (roadmap I-B2): the page gets a new capability, and every link already sent (e-mails, Shopify's tracking link, a printed packing slip) shows 'no longer valid' with the lookup form. Irreversible. Answers revoked: false when the order has no page yet. customerPages_open answers the new link.\n\n**Operation id:** `customerPages_revoke` — the same operation is `app.customerPages.revoke({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/customerPages_revoke`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/abandon-precommit": { "post": { "operationId": "order_edit_abandon_precommit", "summary": "order_edit_abandon_precommit", "description": "Abandon only a stopped original preparation attempt with no commit claim or commit proof, preserving its fingerprint and delivery evidence. Never retries Shopify or unlocks an uncertain commit.\n\n**Operation id:** `order_edit_abandon_precommit` — the same operation is `app.order.edit_abandon_precommit({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_abandon_precommit`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "A orderEditSessions id, e.g. \"orderEditSessions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedUpdatedAt": { "type": "number" }, "expectedStepKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "expectedFingerprint": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "sessionId", "expectedUpdatedAt", "expectedStepKey", "expectedFingerprint" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/add-variant": { "post": { "operationId": "order_edit_add_variant", "summary": "order_edit_add_variant", "description": "Stage adding a variant to an open order edit session (maps to Shopify orderEditAddVariant). Name the session, or the order: its open session, begun by this change when it has none. Returns the session and the updated local price preview.\n\n**Operation id:** `order_edit_add_variant` — the same operation is `app.order.edit_add_variant({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_add_variant`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "description": "document id of the order edit session.", "type": "string", "format": "floormode-id" }, "shopifyOrderId": { "description": "Numeric Shopify order id as a string, instead of sessionId.", "type": "string", "minLength": 1, "format": "floormode-id" }, "shopifyVariantId": { "description": "Numeric Shopify variant id as a string.", "type": "string", "format": "floormode-id" }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 } }, "required": [ "quantity" ], "oneOf": [ { "required": [ "sessionId" ] }, { "required": [ "shopifyOrderId" ] } ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/begin": { "post": { "operationId": "order_edit_begin", "summary": "order_edit_begin", "description": "Open an order edit session (OMS-074) for staging line changes. Returns the existing open session for the order if one is already open. Optional: a staging call that names the order begins the session with its first change. Changes are staged locally and applied to Shopify (orderEditBegin → add/set → orderEditCommit) only on commit.\n\n**Operation id:** `order_edit_begin` — the same operation is `app.order.edit_begin({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_begin`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } }, "required": [ "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/cancel": { "post": { "operationId": "order_edit_cancel", "summary": "order_edit_cancel", "description": "Discard an open order edit session without touching Shopify.\n\n**Operation id:** `order_edit_cancel` — the same operation is `app.order.edit_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "document id of the order edit session.", "format": "floormode-id" } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/commit": { "post": { "operationId": "order_edit_commit", "summary": "order_edit_commit", "description": "Commit a staged order edit: queues one Shopify order-edit flow (orderEditBegin → add-variant / set-quantity → orderEditCommit). The session goes to committing and the outbox outcome settles it. Fails if there are no staged changes. A split-item replacement requires the current review token from order_edit_get; this acknowledges a possible Shopify refusal.\n\n**Operation id:** `order_edit_commit` — the same operation is `app.order.edit_commit({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_commit`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "document id of the order edit session.", "format": "floormode-id" }, "note": { "description": "Staff note recorded on the Shopify order edit.", "type": "string", "minLength": 1, "maxLength": 500 }, "reviewedSplitToken": { "description": "Current splitReplacementReview.token acknowledged after reviewing the provider risk and fulfillment state.", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/get": { "get": { "operationId": "order_edit_get", "summary": "order_edit_get", "description": "Get one order edit session with its staged changes and the local price preview (added subtotal, quantity delta, net delta), plus a current split-replacement risk review when applicable.\n\n**Operation id:** `order_edit_get` — the same operation is `app.order.edit_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "document id of the order edit session.", "schema": { "type": "string", "description": "document id of the order edit session.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/list": { "get": { "operationId": "order_edit_list", "summary": "order_edit_list", "description": "List order edit sessions. With shopifyOrderId, the sessions of that order; otherwise the open sessions across the tenant (max 20).\n\n**Operation id:** `order_edit_list` — the same operation is `app.order.edit_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": false, "description": "Numeric Shopify order id as a string.", "schema": { "description": "Numeric Shopify order id as a string.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/recovery": { "get": { "operationId": "order_edit_recovery", "summary": "order_edit_recovery", "description": "Inspect original durable step and delivery evidence for an uncertain Shopify order edit. A commit claim is never inferred from current order shape.\n\n**Operation id:** `order_edit_recovery` — the same operation is `app.order.edit_recovery({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_recovery`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "A orderEditSessions id, e.g. \"orderEditSessions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A orderEditSessions id, e.g. \"orderEditSessions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/set-added-quantity": { "post": { "operationId": "order_edit_set_added_quantity", "summary": "order_edit_set_added_quantity", "description": "Set a staged added variant quantity; zero removes the staged addition.\n\n**Operation id:** `order_edit_set_added_quantity` — the same operation is `app.order.edit_set_added_quantity({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_set_added_quantity`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "shopifyVariantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "quantity": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "sessionId", "shopifyVariantId", "quantity" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/set-line-discount": { "post": { "operationId": "order_edit_set_line_discount", "summary": "order_edit_set_line_discount", "description": "Stage a manual discount on an unfulfilled line. Null removes the editable manual line discount. Shopify confirms financial totals; no inventory, payment or refund is performed locally. Name the session, or the order: its open session, begun by this change when it has none.\n\n**Operation id:** `order_edit_set_line_discount` — the same operation is `app.order.edit_set_line_discount({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_set_line_discount`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "description": "document id of the order edit session.", "type": "string", "format": "floormode-id" }, "shopifyOrderId": { "description": "Numeric Shopify order id as a string, instead of sessionId.", "type": "string", "minLength": 1, "format": "floormode-id" }, "shopifyLineItemId": { "type": "string", "minLength": 1, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "discount": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "value": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, "description": { "type": "string", "maxLength": 255 } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "value": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" }, "description": { "type": "string", "maxLength": 255 } }, "required": [ "type", "value" ] } ] }, { "type": "null" } ] } }, "required": [ "shopifyLineItemId", "discount" ], "oneOf": [ { "required": [ "sessionId" ] }, { "required": [ "shopifyOrderId" ] } ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/edit/set-quantity": { "post": { "operationId": "order_edit_set_quantity", "summary": "order_edit_set_quantity", "description": "Stage changing an existing order line's quantity on an open edit session (maps to Shopify orderEditSetQuantity). Setting it back to the original quantity drops the staged change. Name the session, or the order: its open session, begun by this change when it has none. Returns the session and the updated local price preview.\n\n**Operation id:** `order_edit_set_quantity` — the same operation is `app.order.edit_set_quantity({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_edit_set_quantity`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "description": "document id of the order edit session.", "type": "string", "format": "floormode-id" }, "shopifyOrderId": { "description": "Numeric Shopify order id as a string, instead of sessionId.", "type": "string", "minLength": 1, "format": "floormode-id" }, "shopifyLineItemId": { "type": "string", "description": "Numeric Shopify order line item id as a string.", "format": "floormode-id" }, "newQuantity": { "type": "integer", "minimum": 0, "maximum": 100000 }, "restock": { "description": "Required for reductions: whether Shopify should restock removed units.", "type": "boolean" } }, "required": [ "shopifyLineItemId", "newQuantity" ], "oneOf": [ { "required": [ "sessionId" ] }, { "required": [ "shopifyOrderId" ] } ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/get": { "get": { "operationId": "orders_get", "summary": "orders_get", "description": "Get one mirrored Shopify order in full: the order itself, its line items, its fulfillment orders, its fulfillments, its ALLOCATIONS and its open HOLD INTENTS. Each allocation carries its state, its reserved lines with bin code and quantity, whatever could not be reserved (shortQty) and any backordered units — including the KIT-EXPANSION lines, where a BOM parent is expanded into component lines carrying componentKind (physical or virtual/VMAT), componentPerParent and the parent units those components cover, so a kit order shows what is actually being picked rather than only the parent sku. Hold intents name their reason and the document that caused them. `actions` is the merged list of Shopify actions the fulfillment orders currently permit. Accepts EITHER identifier in `shopifyOrderId`: Shopify's numeric order id, or this app's own order document id as returned by orders_list._id. An unknown id returns null, not an error. Child collections are capped, so a very large order is truncated rather than unbounded. `hasShortfall` says whether any non-released allocation still owes units it could not reserve — read over every allocation line, so it holds even when the lines shown were cut. `linePricing` gives each listed line's unit price, its discount as an amount and its line total, null while Shopify's discounted total for the line is unknown. `dueAt` / `dueKind` (pack_day or fulfill_by) and `fulfillmentOrderDues` (one per listed fulfillment order) follow the one due rule: due = the end of the pack day (the warehouse's packing day before the customer's requested delivery day, in the warehouse's time zone) for work at a warehouse with a requested delivery date while delivery dates are on, else Shopify's fulfil-by; `deliveryDate` adds the pack day and its warehouse. `fulfillmentOrderCheckoutOptions` (one per listed fulfillment order) says what the customer chose at checkout and what it ships with: the option, its `resolution` (mapped, mapped_unavailable when the mapped service was not offered for the newest shipment, rules, unreviewed, ambiguous, pending, non_shipping), the mapped carrier service and the option's revision for checkout_options_set_target.\n\n**Operation id:** `orders_get` — the same operation is `app.orders.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Numeric Shopify order id as a string (\"450789469\"), OR this app's order document id from orders_list._id (\"orders_01ARZ…\"). The prefix distinguishes them.", "schema": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string (\"450789469\"), OR this app's order document id from orders_list._id (\"orders_01ARZ…\"). The prefix distinguishes them.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/journey": { "get": { "operationId": "orders_journey", "summary": "orders_journey", "description": "One order's journey, oldest first, computed from the order's own records: Shopify created and changed it, where Shopify routed it, the reservations, holds and steps Floormode declined, picking, packing and labels, every update queued for Shopify, a carrier or a connected app (state, attempts, the destination's own words for its last refusal and when it is tried next), Shopify's fulfillments and the carrier's tracking. Answers why an order is not in Shopify yet. Each source is bounded and `capped` names the ones cut. Deliveries Shopify sent that changed nothing are not kept and do not appear.\n\n**Operation id:** `orders_journey` — the same operation is `app.orders.journey({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_journey`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Numeric Shopify order id as a string, or this app's order document id.", "schema": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string, or this app's order document id.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges": { "get": { "operationId": "order_merges_list", "summary": "order_merges_list", "description": "Order merge groups, a disclosed page at a time (`rows`/`capped`/`cursor`, max 100), newest first (`created:desc`, the default) or oldest first, with each group's member order ids. Filters are server predicates: `statuses` (any of open, fulfilled, cancelled) and `shopifyOrderId` (only groups that order belongs to). A group closes as `fulfilled` by itself once no member order has an open fulfillment order left (a cancelled member counts as done), and as `cancelled` when every member was cancelled. Breaking since 2026-10-07: the former single-valued `status` is refused; pass `statuses: [\"open\"]`.\n\n**Operation id:** `order_merges_list` — the same operation is `app.order.merges_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Any of open, fulfilled, cancelled; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of open, fulfilled, cancelled; absent = every status.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "open", "cancelled", "fulfilled" ] } } }, { "name": "shopifyOrderId", "in": "query", "required": false, "description": "Only groups this Shopify order is a member of.", "schema": { "description": "Only groups this Shopify order is a member of.", "type": "string", "minLength": 1, "format": "floormode-id" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Groups per page (max 100).", "schema": { "description": "Groups per page (max 100).", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "order_merges_create", "summary": "order_merges_create", "description": "Create a cross-order merge group (OMS-073) from two or more open orders shipping to the same address, so the warehouse picks and packs them together. This is INTERNAL grouping only — Shopify has no merge primitive, so each order is still fulfilled through its own fulfillment orders; the group only drives the combined pick/pack view.\n\n**Operation id:** `order_merges_create` — the same operation is `app.order.merges_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderIds": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "Numeric Shopify order ids — at least two distinct, at most 20." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "shopifyOrderIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges/add-order": { "post": { "operationId": "order_merges_add_order", "summary": "order_merges_add_order", "description": "Add one more matching open order to an open merge group.\n\n**Operation id:** `order_merges_add_order` — the same operation is `app.order.merges_add_order({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_add_order`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "document id of the merge group.", "format": "floormode-id" }, "shopifyOrderId": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } }, "required": [ "groupId", "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges/cancel": { "post": { "operationId": "order_merges_cancel", "summary": "order_merges_cancel", "description": "Cancel an open merge group; cancelling a cancelled one is a no-op, and a `fulfilled` group is terminal and refused (`illegal_transition`). Its member orders are untouched.\n\n**Operation id:** `order_merges_cancel` — the same operation is `app.order.merges_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "document id of the merge group.", "format": "floormode-id" } }, "required": [ "groupId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges/get": { "get": { "operationId": "order_merges_get", "summary": "order_merges_get", "description": "Get one merge group with its member orders.\n\n**Operation id:** `order_merges_get` — the same operation is `app.order.merges_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "groupId", "in": "query", "required": true, "description": "document id of the merge group.", "schema": { "type": "string", "description": "document id of the merge group.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges/remove-order": { "post": { "operationId": "order_merges_remove_order", "summary": "order_merges_remove_order", "description": "Remove one order from a merge group. The group is cancelled if fewer than two orders remain.\n\n**Operation id:** `order_merges_remove_order` — the same operation is `app.order.merges_remove_order({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_remove_order`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "document id of the merge group.", "format": "floormode-id" }, "shopifyOrderId": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } }, "required": [ "groupId", "shopifyOrderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/merges/view": { "get": { "operationId": "order_merges_view", "summary": "order_merges_view", "description": "Current order contents of a merge group: positive current line quantities rolled up by SKU with a per-order breakdown. Removed quantities are excluded; these are not remaining pick quantities.\n\n**Operation id:** `order_merges_view` — the same operation is `app.order.merges_view({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/order_merges_view`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "groupId", "in": "query", "required": true, "description": "document id of the merge group.", "schema": { "type": "string", "description": "document id of the merge group.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/pick-early": { "post": { "operationId": "orders_set_pick_early", "summary": "orders_set_pick_early", "description": "Let one order through to picking before its pack day (early: true), or make it wait for its pack day again (delivery dates D2). Where a warehouse's picking waits for the pack day (settings.pickOnPackDay), an order with a requested delivery day is not ready to pick before it; a released order is. The release stands through later syncs and a changed delivery day. A cancelled or fulfilled order is refused (work_closed); asking for what the order already says is a no-op.\n\n**Operation id:** `orders_set_pick_early` — the same operation is `app.orders.set_pick_early({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_set_pick_early`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "early": { "type": "boolean", "description": "true lets it through before its pack day; false makes it wait again." } }, "required": [ "shopifyOrderId", "early" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/queue": { "get": { "operationId": "orders_work_queue", "summary": "orders_work_queue", "description": "Order work queue (up to 50 per page, `limit`; newest first by default): the list rows plus a bounded rollup per order — open/held fulfillment-order counts, allocation state (none/allocated/short/released), why the order is blocked (an open hold with its reason, note and covering document, or a stock shortfall) plus how many distinct skus are missing, destination city+country, the delivery methods of its fulfillment orders (`deliveryMethods`: shipping, pickup, local_delivery, other) and the order age in milliseconds. Filter by fulfillment status, hold state, hold reason, allocation state, risk level, tag, ship-to country code (`destinationCountry`), delivery method (`deliveryMethod`, any of the listed methods), orders placed at or after an instant (`createdAfterMs`) or a search over order name, customer name and email, or to the orders with a line of one variant; sort newest first (default) or oldest first (`sort`); paginate with `cursor` (a cursor belongs to the sort it was returned under; `limit` sizes the page, 50 by default). The status alias \"open\" (not fulfilled AND not cancelled — Shopify leaves the status null while nothing is fulfilled, and a cancelled order is excluded whatever its fulfillment status says) is what the orders screen shows by default. Each row's `dueAt` is the earliest due of its open work and `dueKind` its rule: due = the end of the pack day (the warehouse's packing day before the customer's requested delivery day, in the warehouse's time zone) for work at a warehouse with a requested delivery date while delivery dates are on, else Shopify's fulfil-by; `packDay` is its earliest pack day. `packDay` (the filter) narrows to open orders by pack day.\n\n**Operation id:** `orders_work_queue` — the same operation is `app.orders.work_queue({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_work_queue`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "One or more fulfillment statuses, e.g. [\"unfulfilled\", \"partial\"] or [\"fulfilled\"]. \"open\" means unfulfilled or partial and not cancelled, the default. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "One or more fulfillment statuses, e.g. [\"unfulfilled\", \"partial\"] or [\"fulfilled\"]. \"open\" means unfulfilled or partial and not cancelled, the default.", "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1 } } }, { "name": "holdState", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "held", "unheld" ] } }, { "name": "allocationState", "in": "query", "required": false, "description": "Stock reserved for the whole order: none, allocated (fully reserved), short (stock missing) or released.", "schema": { "description": "Stock reserved for the whole order: none, allocated (fully reserved), short (stock missing) or released.", "type": "string", "enum": [ "none", "allocated", "short", "released" ] } }, { "name": "holdReason", "in": "query", "required": false, "description": "Only orders carrying one of OUR open holds with this reason.", "schema": { "description": "Only orders carrying one of OUR open holds with this reason.", "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other" ] } }, { "name": "riskLevel", "in": "query", "required": false, "description": "Risk level, e.g. \"HIGH\" (case-insensitive).", "schema": { "description": "Risk level, e.g. \"HIGH\" (case-insensitive).", "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Exact order tag, compared like an automation rule: case-, space- and accent-composition-insensitive (RÜCKSENDUNG finds Rücksendung).", "schema": { "description": "Exact order tag, compared like an automation rule: case-, space- and accent-composition-insensitive (RÜCKSENDUNG finds Rücksendung).", "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Substring of order name, customer name or email.", "schema": { "description": "Substring of order name, customer name or email.", "type": "string" } }, { "name": "variantId", "in": "query", "required": false, "description": "document id of a variant: only orders with a line of it.", "schema": { "description": "document id of a variant: only orders with a line of it.", "type": "string", "format": "floormode-id" } }, { "name": "updatedBeforeMs", "in": "query", "required": false, "description": "Orders Shopify last changed before this instant (milliseconds since 1970, UTC). An order whose change time could not be read never matches.", "schema": { "description": "Orders Shopify last changed before this instant (milliseconds since 1970, UTC). An order whose change time could not be read never matches.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "createdAfterMs", "in": "query", "required": false, "description": "Orders placed at or after this instant (milliseconds since 1970, UTC).", "schema": { "description": "Orders placed at or after this instant (milliseconds since 1970, UTC).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "destinationCountry", "in": "query", "required": false, "description": "Ship-to country as a two-letter ISO code, e.g. DE.", "schema": { "description": "Ship-to country as a two-letter ISO code, e.g. DE.", "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "deliveryMethod", "in": "query", "required": false, "description": "Any of these delivery methods, e.g. [\"pickup\", \"local_delivery\"]: orders the customer collects or the merchant delivers. Every method when absent. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these delivery methods, e.g. [\"pickup\", \"local_delivery\"]: orders the customer collects or the merchant delivers. Every method when absent.", "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "shipping", "pickup", "local_delivery", "other" ] } } }, { "name": "packDay", "in": "query", "required": false, "description": "Open orders by pack day in each warehouse's own today: overdue, today, next, later, no_date or unreadable. Refused as delivery_dates_off while off. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Open orders by pack day in each warehouse's own today: overdue, today, next, later, no_date or unreadable. Refused as delivery_dates_off while off.", "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "overdue", "today", "next", "later", "no_date", "unreadable" ] } } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "shippingOption", "in": "query", "required": false, "description": "Orders with a fulfillment order under this checkout option, an id from checkout_options_list. With open statuses only: open fulfillment orders only.", "schema": { "description": "Orders with a fulfillment order under this checkout option, an id from checkout_options_list. With open statuses only: open fulfillment orders only.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "`cursor` returned by the previous page.", "schema": { "description": "`cursor` returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1 to 50; the default is 50.", "schema": { "description": "Rows per page, 1 to 50; the default is 50.", "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/refund": { "post": { "operationId": "orders_refund", "summary": "orders_refund", "description": "Refund an order in Shopify (OMS-1 G-02): chosen items, optionally putting unshipped units back into stock, shipping, or an amount on its own. Admitted only while no other refund, cancellation, capture, item edit or open return request is in flight; a refusal names its reason in details.code (for example refund_in_flight, open_return or nothing_captured). Items are checked against what each line can still refund; while earlier returns of the order are still being confirmed with Shopify the answer is ok false with reason order_checking, nothing is queued and the same key may be sent again. Before any money moves Floormode reads Shopify's own refund suggestion: when Shopify would refund more than the confirmed maximum, when the order was paid in another currency than the shop's, or when the order's payments cannot cover the amount exactly, Shopify is asked nothing and the request settles as not applied. A refund that restocks pauses NEW floor work on the order until Shopify's answer is mirrored. The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `orders_refund` — the same operation is `app.orders.refund({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_refund`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "lines": { "default": [], "description": "The items to refund; empty for a refund of shipping or of an amount only.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "shopifyLineItemId": { "type": "string", "minLength": 1, "description": "Numeric Shopify line item id, as listed in the order's lineItems.", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Units of the line to refund." }, "restock": { "type": "boolean", "description": "Put these units back into Shopify stock. Unshipped units only: Shopify removes them from the order, and new floor work on the order waits for the answer." } }, "required": [ "shopifyLineItemId", "quantity", "restock" ] } }, "shippingAmount": { "description": "Shipping to refund, in the order's currency (for example 4.95). Shopify refuses more than it can still refund.", "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "amount": { "description": "An amount to refund on its own, without items or shipping, in the order's currency. It goes back to the order's payments in Shopify's order and must be covered exactly.", "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "note": { "description": "Why the order is refunded; kept on the refund.", "type": "string", "maxLength": 500 }, "notifyCustomer": { "type": "boolean", "description": "Send Shopify's refund email to the customer." } }, "required": [ "shopifyOrderId", "requestKey", "notifyCustomer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/refund-quote": { "get": { "operationId": "orders_refund_quote", "summary": "orders_refund_quote", "description": "What an order can refund right now (OMS-1 G-02), per line: the units still refundable, restockable and returnable, and what the customer paid for the whole line in micros of the order's currency. Read from the mirror only, as the hint for the refund form: the exact amount is Shopify's own suggestion, read again before any refund is issued, and a refund above the quoted maximum is refused. complete is false while earlier returns are still being confirmed. An unknown order returns null.\n\n**Operation id:** `orders_refund_quote` — the same operation is `app.orders.refund_quote({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_refund_quote`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "shopifyOrderId", "in": "query", "required": true, "description": "Numeric Shopify order id as a string.", "schema": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/split": { "post": { "operationId": "orders_split", "summary": "orders_split", "description": "Split a fulfillment order's stock shortages into a new fulfillment order (OMS-073) so the covered units can ship now while the missing units wait for restock. Queues the Shopify `fulfillmentOrderSplit`; requires the fulfillment order to still support SPLIT and to have both covered and short remaining units, with no picked goods. Oversell need not be enabled. Identify it by shopifyFoId or its document id.\n\n**Operation id:** `orders_split` — the same operation is `app.orders.split({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_split`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "foDocId": { "type": "string", "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "shopifyFoId": { "description": "Numeric Shopify fulfillment order id.", "type": "string", "format": "floormode-id" } } } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/tags": { "get": { "operationId": "orders_recent_tags", "summary": "orders_recent_tags", "description": "The tags and priorities on recent orders, for writing pick profile and automation conditions: a sample of the newest 1,000 orders of the last 90 days, grouped case-insensitively with the most frequent spelling and the number of orders carrying each, in `value` (`truncated` = the sample was full, so older orders may carry other tags and every count is a floor), plus the tags live automation rules add and, with warehouseId, the tags and priorities that warehouse's live pick profiles use. A tag added by a rule appears on orders a moment after the rule runs.\n\n**Operation id:** `orders_recent_tags` — the same operation is `app.orders.recent_tags({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_recent_tags`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Also offer the tags this warehouse's live pick profiles use.", "schema": { "description": "Also offer the tags this warehouse's live pick profiles use.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/orders/update": { "post": { "operationId": "orders_update", "summary": "orders_update", "description": "Change an order's note, tags, contact email or shipping address in Shopify (OMS-1 G-03/G-04). Send only what changes, with expectedUpdatedAt as orders_get returned it: an order that changed since is refused with revision_mismatch, and Shopify's own copy is checked again before any field is written, so a newer change there is never overwritten. An address change is refused while a label is being bought or was bought, or a freight tender runs; once admitted, new labels and tenders for the order wait for it, and rates or freight offers fetched for the old address must be fetched again. A refusal names its reason in details.code. The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `orders_update` — the same operation is `app.orders.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/orders_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "orders" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "expectedUpdatedAt": { "type": "string", "minLength": 1, "description": "The order's shopifyUpdatedAt exactly as the caller read it from orders_get. An order that changed since is refused with revision_mismatch, and Shopify's own copy is checked again before any field is written." }, "note": { "description": "The order note. Null or an empty string clears it; absent leaves it unchanged.", "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "tags": { "description": "Tag changes. A tag cannot be added and removed in one request.", "type": "object", "properties": { "add": { "maxItems": 250, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40, "description": "One order tag (at most 40 characters)." }, "description": "Tags to add; the order's other tags stay." }, "remove": { "maxItems": 250, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40, "description": "One order tag (at most 40 characters)." }, "description": "Tags to remove; the order's other tags stay." } }, "required": [ "add", "remove" ] }, "email": { "description": "The order's contact email; a malformed address is refused with invalid_input. Refused with details_withheld while Shopify withholds this order's customer details from the app.", "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "shippingAddress": { "description": "The whole new shipping address. Refused while a label is being bought or was bought (label_in_flight) or a freight tender runs (freight_booking); once admitted, rates and freight offers fetched for the old address stop counting.", "type": "object", "properties": { "firstName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Recipient first name." }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Recipient last name." }, "company": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Company, if any." }, "address1": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street and house number." }, "address2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Apartment, suite, floor." }, "city": { "type": "string", "minLength": 1, "maxLength": 255, "description": "City." }, "provinceCode": { "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ], "description": "ISO 3166-2 subdivision code without the country prefix (for example BY or CA), where the country has provinces." }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code, for example DE." }, "zip": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "description": "Postal code." }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "A phone number the carrier may call." } }, "required": [ "firstName", "lastName", "company", "address1", "address2", "city", "provinceCode", "countryCode", "zip", "phone" ] } }, "required": [ "shopifyOrderId", "requestKey", "expectedUpdatedAt" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/pack-instructions/get": { "get": { "operationId": "pack_instructions_get", "summary": "pack_instructions_get", "description": "Get the pack instructions of one product: the product's own note and each variant's own note (variantId set), from Floormode (source floormode) or a Shopify metafield (source metafield; Floormode's wins at each level). A packer sees the product's note, then the variant's, and confirms when either asks. Also answers the product's Shopify image a note may show and how many live variants share the product's note. With variantId, only the product's own notes and that variant's, whole; without, one page of every note (notesCapped says when there are more). Null for an unknown product.\n\n**Operation id:** `pack_instructions_get` — the same operation is `app.pack.instructions_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_instructions_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "pack-instructions" ], "x-operation-kind": "query", "parameters": [ { "name": "productId", "in": "query", "required": true, "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": false, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/pack-instructions/import": { "post": { "operationId": "pack_instructions_import", "summary": "pack_instructions_import", "description": "Import pack instructions in bulk, at most 500 rows per call: each row names a live item by its SKU, with its instruction (empty removes it) and optionally confirm. A product with one live variant gets the product's note, a product with several gets that variant's own. A row whose SKU names no item, or several, is reported in errors and the other rows are written. A row keeps the note's image, and its confirm when the row gives none. The requestKey binds the sheet: the same rows under the same key answer the first result again (replayed: true) and write nothing; other rows under it are refused.\n\n**Operation id:** `pack_instructions_import` — the same operation is `app.pack.instructions_import({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_instructions_import`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "pack-instructions" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "rows": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1 }, "instruction": { "type": "string", "maxLength": 280 }, "confirm": { "type": "boolean" } }, "required": [ "sku", "instruction" ] } } }, "required": [ "requestKey", "rows" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/pack-instructions/save": { "post": { "operationId": "pack_instructions_save", "summary": "pack_instructions_save", "description": "Write the Floormode pack instruction of a product (variantId null) or of one of its variants: plain text of at most 280 characters (empty removes the note), an optional image that is one of the product's Shopify images (https://cdn.shopify.com/…), and confirm (the packer must confirm it before the parcel can be fulfilled). Send the note's revision from pack_instructions_get, 0 for a new note; a note changed since is refused with revision_mismatch. Answers the stored note, or null once removed.\n\n**Operation id:** `pack_instructions_save` — the same operation is `app.pack.instructions_save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_instructions_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "pack-instructions" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "description": "A products id, e.g. \"products_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "variantId": { "anyOf": [ { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "text": { "type": "string", "maxLength": 280 }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "confirm": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "productId", "variantId", "text", "imageUrl", "confirm", "revision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/ack-instruction": { "post": { "operationId": "packing_ack_instruction", "summary": "packing_ack_instruction", "description": "Confirm a line's pack instruction at the pack station: the packer read the note of an item whose instruction asks to be confirmed (packing_get items[].instruction.confirm). Once per line, whatever its quantity: a second confirm writes nothing and answers replayed: true. Refused for an item that is not in the parcel or has nothing to confirm, and once the parcel is packed. While a confirm is missing, the instructions step is open and packing_fulfill answers instructions_required.\n\n**Operation id:** `packing_ack_instruction` — the same operation is `app.packing.ack_instruction({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_ack_instruction`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "packJobId", "variantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/confirm-item": { "post": { "operationId": "packing_confirm_item", "summary": "packing_confirm_item", "description": "Confirms `qty` units of one parcel item by eye (method tap), for an item no scan finds (no barcode, SKU or alias) or one allowed to be confirmed without a scan (variants_set_confirm_mode no_scan). Counted exactly like scans of it, at most what is still open (over_scan otherwise); an item a scan finds and not allowed without a scan is refused as \"has_code\" with the code to scan. Where the warehouse confirms by scan only, an item without the exception needs a lead's grant (`approvalId`), else it is refused as \"scan_required\". Answers like packing_scan_item.\n\n**Operation id:** `packing_confirm_item` — the same operation is `app.packing.confirm_item({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_confirm_item`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "method": { "type": "string", "const": "tap" }, "approvalId": { "description": "A lead's single-use grant where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId", "variantId", "qty", "method" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/details": { "get": { "operationId": "pack_records_list", "summary": "pack_records_list", "description": "Recorded packing details, oldest first, current values only unless `includeSuperseded`: one parcel's (packJobId), one order's (orderId), or every parcel's recorded in a window [fromMs, toMs) — the long export of every value. Every scope pages on `cursor` (oldest first, by record time): a cut page answers where the next one starts. Each row carries its parcel's short id, its field's key and where it shows today, the name, type and unit it was recorded under, the line, the value (a number, a yes/no, or words), how it was given, when, and when a correction replaced it.\n\n**Operation id:** `pack_records_list` — the same operation is `app.pack.records_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_records_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "packJobId", "in": "query", "required": false, "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "orderId", "in": "query", "required": false, "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "fromMs", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "toMs", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "includeSuperseded", "in": "query", "required": false, "description": "Add the values a later correction replaced (default: current values only). Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Add the values a later correction replaced (default: current values only).", "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "description": "Where the next page starts: the cursor a cut page answered (every scope).", "schema": { "description": "Where the next page starts: the cursor a cut page answered (every scope).", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "pack_records_set", "summary": "pack_records_set", "description": "Record packing details on a parcel that is still at the bench. Each value names its active field (and, for a field recorded per line, the line's variant as lineKey) and is checked against it: a number for a number field, true or false for a yes/no, one of a choice's options by key or name, words matching the pattern for a text or a seal. A value is never edited: a new one supersedes the one on record, an unchanged one writes nothing, null clears it. Refused once the parcel is packed (parcel_packed). `source` is how a packer gave it (manual or scan); absent = api. Answers only the records the call changed (a cleared value's ended record carries supersededAtMs) and `missing`, the required values the parcel still lacks.\n\n**Operation id:** `pack_records_set` — the same operation is `app.pack.records_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_records_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "values": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "description": "A packFields id, e.g. \"packFields_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "lineKey": { "description": "The line's variant id, for a field recorded per line.", "type": "string" }, "value": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "source": { "description": "How the packer gave it; absent = api.", "type": "string", "enum": [ "manual", "scan" ] } }, "required": [ "fieldId", "value" ] } }, "stationId": { "description": "The pack station the values were recorded at.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId", "values" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/fields": { "get": { "operationId": "pack_fields_list", "summary": "pack_fields_list", "description": "The packing details a merchant asks packers to record on parcels (roadmap A1e): the active fields in list order — key (custom.), name, help line, type (text, number, choice, boolean, seal), unit, options, pattern, scope (once per parcel, or once per line), required, where the value shows besides export and the API (order, shipment, packing_slip), status, version and revision. `includeArchived` adds the newest 50 archived fields after them.\n\n**Operation id:** `pack_fields_list` — the same operation is `app.pack.fields_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_fields_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "description": "Add the newest 50 archived fields after the active ones. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Add the newest 50 archived fields after the active ones.", "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "pack_fields_save", "summary": "pack_fields_save", "description": "Create a packing detail field (no fieldId: added at the end of the list) or change one (fieldId with the revision the edit started from; a field saved since answers revision_mismatch). The key is set once, derived from the name unless given, and never renamed (a key another field holds is a key_taken conflict). Changing the type, the unit, the options, the pattern or the scope raises the field's version: values recorded before keep the name, type and unit they were recorded under, and stop counting for the pack step. A choice takes 2 to 50 options; a pattern must compile. At most 20 active fields (too_many_fields).\n\n**Operation id:** `pack_fields_save` — the same operation is `app.pack.fields_save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_fields_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "description": "The field to change; absent creates a field at the end of the list.", "type": "string", "format": "floormode-id" }, "expectedRevision": { "description": "The revision the edit started from (required with fieldId).", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "key": { "description": "custom., set once on create and never renamed; absent = derived from the label.", "type": "string", "maxLength": 47 }, "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "help": { "anyOf": [ { "type": "string", "maxLength": 140 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "text", "number", "choice", "boolean", "seal" ] }, "unit": { "description": "A number field's unit (g, cm, pieces …).", "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "options": { "description": "A choice field's options, in order, by their labels.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "pattern": { "description": "A regular expression a text or seal value must match.", "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "parcel", "line" ] }, "required": { "type": "boolean" }, "showOn": { "type": "array", "items": { "type": "string", "enum": [ "order", "shipment", "packing_slip" ] }, "description": "Where the value shows besides export and the API, which see every field." } }, "required": [ "label", "type", "scope", "required", "showOn" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/fields/archive": { "post": { "operationId": "pack_fields_archive", "summary": "pack_fields_archive", "description": "Archive a packing detail field: it leaves the pack step and the other fields close the gap; every value recorded under it stays readable, and it can be restored.\n\n**Operation id:** `pack_fields_archive` — the same operation is `app.pack.fields_archive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_fields_archive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string", "description": "A packFields id, e.g. \"packFields_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "fieldId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/fields/reorder": { "post": { "operationId": "pack_fields_reorder", "summary": "pack_fields_reorder", "description": "Put the active packing detail fields in a new order. `fieldIds` names every active field exactly once; a list from a stale screen is refused as a conflict.\n\n**Operation id:** `pack_fields_reorder` — the same operation is `app.pack.fields_reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_fields_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "description": "A packFields id, e.g. \"packFields_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "description": "Every active field exactly once, in the new order." } }, "required": [ "fieldIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/fields/restore": { "post": { "operationId": "pack_fields_restore", "summary": "pack_fields_restore", "description": "Restore an archived packing detail field to the end of the list, if fewer than 20 are active (too_many_fields).\n\n**Operation id:** `pack_fields_restore` — the same operation is `app.pack.fields_restore({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_fields_restore`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string", "description": "A packFields id, e.g. \"packFields_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "fieldId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/fulfill": { "post": { "operationId": "packing_fulfill", "summary": "packing_fulfill", "description": "Queue the Shopify fulfillment of a verified pack job (status fulfill_queued). The tenant object only records the intent: the Worker executes `fulfillmentCreate` with the selected picked fulfillment-order quantities (omitted selection means all picked remainder) and tracking. Partial selections require the current packing_get fulfillmentOptions revision; queued retries preserve the frozen parcel. The stock leaves the staging bin only once Shopify confirms — Shopify stays the truth for shipped. Answers an outcome: `{ ok: true, value }` once queued, or `{ ok: false, reason, detail }` when a step of the warehouse's pack checklist is unmet (judged only for a verified parcel with no standing attempt): `_required` — `qc_required` (the check holds no pass, or a recorded fail), `label_required` (the label step is required and neither a label of this parcel nor a tracking number exists), `weigh_required` (the weight is required and none is recorded), and `photo_required`, `details_required`, `instructions_required` as those steps arrive; packing_get's `steps` and `unmetSteps` say so beforehand. A pickup or local-delivery parcel (packing_get `deliveryMethod`) takes no label and gets no fulfillment of ours, and must hold everything its fulfillment order still owes: pickup queues Shopify's `fulfillmentOrderLineItemsPreparedForPickup` (status fulfill_queued, then prepared once Shopify confirms; Shopify sends the customer its ready-for-pickup notice), local delivery becomes prepared at once with no Shopify call (`outboxId: null`; Shopify has no such call). A prepared parcel ships when Shopify reports the handover fulfillment (picked up / delivered).\n\n**Operation id:** `packing_fulfill` — the same operation is `app.packing.fulfill({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_fulfill`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingCompany": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notifyCustomer": { "type": "boolean" }, "lineItems": { "minItems": 1, "maxItems": 250, "type": "array", "items": { "type": "object", "properties": { "foLineId": { "type": "string", "minLength": 1, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "foLineId", "quantity" ] } }, "expectedFulfillmentRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "stationId": { "description": "The pack station the parcel was finished at; ignored unless a pack station here.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/jobs": { "get": { "operationId": "packing_list_jobs", "summary": "packing_list_jobs", "description": "List pack jobs, in the chosen order (`sort`; newest first by default), one page, with expected and scanned unit counts. Filter by status (pending, verifying, verified, fulfill_queued, fulfilled, failed, cancelled), warehouse or order (orderId). A pack job carries no bin and no station, so zoneId and stationId both narrow to their WAREHOUSE — the finest granularity this surface has. Each row's `shippingOption` is the customer's checkout option and what it ships with, without the shipment fallback (never mapped_unavailable here).\n\n**Operation id:** `packing_list_jobs` — the same operation is `app.packing.list_jobs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_list_jobs`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "pending", "verifying", "verified", "fulfill_queued", "prepared", "fulfilled", "failed", "cancelled" ] } } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "orderId", "in": "query", "required": false, "description": "Only this order's pack jobs (its shipment picker).", "schema": { "description": "Only this order's pack jobs (its shipment picker).", "type": "string", "format": "floormode-id" } }, { "name": "zoneId", "in": "query", "required": false, "description": "Narrows to the zone's warehouse.", "schema": { "description": "Narrows to the zone's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first: the next job to pack).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first: the next job to pack).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/jobs/get": { "get": { "operationId": "packing_get", "summary": "packing_get", "description": "Get one pack job: the parcel's item checklist (expected vs. scanned per variant), the shipping address, whether it is fully verified, the warehouse's pack checklist evaluated for it (`steps`: each step's mode, state — done, open, not_needed, skipped, waiting_lead — and facts as numbers and closed words), the steps still unmet (`unmetSteps`), what the weight is measured against (`weigh`: the parcel's expected weight and the tolerance), the label to pick up from (`dispatch`) and how it reaches the customer (`deliveryMethod`: a pickup or local_delivery parcel takes no label). While delivery dates are on, `requestedDeliveryDay` and the day this warehouse packs it (`packDay`). `shippingOption`: the customer's checkout option and what it ships with (as orders_get's fulfillmentOrderCheckoutOptions).\n\n**Operation id:** `packing_get` — the same operation is `app.packing.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "packJobId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "desk", "in": "query", "required": false, "description": "Also answer confirmSummary, which a pack bench never shows. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Also answer confirmSummary, which a pack bench never shows.", "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/legacy-shipment-reviews": { "get": { "operationId": "packing_legacy_shipment_reviews", "summary": "packing_legacy_shipment_reviews", "description": "List historical fulfilled parcels with unaccounted picked goods and no retained physical shipment proof.\n\n**Operation id:** `packing_legacy_shipment_reviews` — the same operation is `app.packing.legacy_shipment_reviews({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_legacy_shipment_reviews`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": true, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/legacy-shipment-reviews/prepare": { "post": { "operationId": "packing_review_legacy_shipment", "summary": "packing_review_legacy_shipment", "description": "Prepare an explicit physical review of historical picked goods. An exact retained frozen parcel plan upgrades provider ownership; otherwise the review makes no claim about historical shipped quantities. This preparation changes no physical stock.\n\n**Operation id:** `packing_review_legacy_shipment` — the same operation is `app.packing.review_legacy_shipment({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_review_legacy_shipment`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "packJobId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/photos": { "get": { "operationId": "pack_photos_list", "summary": "pack_photos_list", "description": "The photos on record of one parcel (packJobId) or of every parcel of one order (orderId), newest first: when each was taken, at which pack station, its size, and its status — stored (the parcel's current photo), expired (the warehouse's retention deleted it) or redacted (an erasure or the order's deletion deleted it). Metadata only: the image itself is served to a signed-in person by the app, never through this API.\n\n**Operation id:** `pack_photos_list` — the same operation is `app.pack.photos_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pack_photos_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "packJobId", "in": "query", "required": false, "description": "One parcel (a pack job). Give this or orderId.", "schema": { "description": "One parcel (a pack job). Give this or orderId.", "type": "string", "format": "floormode-id" } }, { "name": "orderId", "in": "query", "required": false, "description": "Every parcel of one order. Give this or packJobId.", "schema": { "description": "Every parcel of one order. Give this or packJobId.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/qc": { "post": { "operationId": "packing_record_qc", "summary": "packing_record_qc", "description": "Record the QC verdict at the pack checkpoint (WHT-016). Only meaningful when the warehouse's packChecklist checks parcels (qc.mode required), but always accepted so a packer can note an inspection. A pass clears the gate on packing_fulfill; a fail (needs a reason) blocks fulfillment and is the cue to disposition the complete parcel (disposition_record_damage_bulk with its pack job ID). Callable on a verified — not yet fulfilled — job.\n\n**Operation id:** `packing_record_qc` — the same operation is `app.packing.record_qc({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_record_qc`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "result": { "type": "string", "enum": [ "pass", "fail" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "packJobId", "result" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/record-serial": { "post": { "operationId": "packing_record_serial", "summary": "packing_record_serial", "description": "Record one serial number of a serial-tracked item in an open parcel (packing_get items[].tracking.mode serial): what the serials step of the parcel's checklist asks for, one serial per unit. A GS1 code's serial (AI 21) is taken out of it, and its GTIN must name the item. Serials are matched case-insensitively. A first capture creates the unit as packed; a unit in stock or returned is packed again. Recording the same serial again answers replayed: true. Refused as a conflict (details.code) when the item is not a serial item of the parcel (not_a_serial_item), every unit already has its serial (serial_count_exceeded), the parcel holds 1000 serials (serial_parcel_full), the unit is packed in another parcel (serial_packed_elsewhere), already shipped (serial_shipped, with the order's name) or scrapped (serial_scrapped), and once the parcel is packed. An item that records its serials at receiving packs only units in stock (serial_not_in_stock); one in stock in another warehouse is taken with a warning and its warehouse corrected. Where the warehouse confirms by scanning, a serial typed on the floor needs a lead's grant (approvalId, action serial_typed). While a serial is missing, packing_fulfill answers serials_required. Shipped with Shopify's confirmation of the fulfilment; returned to where it was when the parcel is cancelled.\n\n**Operation id:** `packing_record_serial` — the same operation is `app.packing.record_serial({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_record_serial`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "serial": { "type": "string", "minLength": 1, "maxLength": 256 }, "method": { "type": "string", "enum": [ "scan", "typed" ], "description": "\"scan\": read by a scanner or camera; \"typed\": typed by hand." }, "approvalId": { "description": "A lead's single-use grant (serial_typed) for a typed serial where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId", "variantId", "serial", "method" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/release-blocked-units": { "post": { "operationId": "packing_release_blocked_units", "summary": "packing_release_blocked_units", "description": "Put a parcel's units of blocked lots aside (packing_fulfill declines it as lot_blocked while it holds any): each staged slice is released with a return-to-shelf task that carries the units back to a shelf, Shopify's commitment for the order untouched, and the order is re-planned onto another lot or short. The parcel then fulfils with the rest. Answers { releasedUnits, lots }.\n\n**Operation id:** `packing_release_blocked_units` — the same operation is `app.packing.release_blocked_units({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_release_blocked_units`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "document id of the pack job.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." } }, "required": [ "packJobId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/remove-serial": { "post": { "operationId": "packing_remove_serial", "summary": "packing_remove_serial", "description": "Take a recorded serial number off an open parcel (packing_get job.serials): the unit goes back to what it was before it was recorded here (in stock, returned), or is deleted when this parcel's capture created it. Refused once the parcel is packed.\n\n**Operation id:** `packing_remove_serial` — the same operation is `app.packing.remove_serial({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_remove_serial`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "serialUnitId": { "type": "string", "description": "A serialUnits id, e.g. \"serialUnits_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "packJobId", "serialUnitId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/scan-item": { "post": { "operationId": "packing_scan_item", "summary": "packing_scan_item", "description": "Scan one item at the pack station. The code is resolved through the scan router server-side and checked against the expected set; failures come back as {ok: false, reason: \"unknown_code\"|\"not_expected\"|\"over_scan\"|\"ambiguous_code\"|\"has_code\"|\"scan_required\", verdict, code, scanCode} without changing anything — `verdict` is the floor's one scan vocabulary (unknown | wrong_target | refused | ambiguous). Send either `code` or `variantId`: an item with no usable code (none of its barcode, alias barcodes or SKU resolves to it in this parcel: it has none, or a bin or another item answers to each first) is named by its variant and counted exactly like a scan of it (the refusal's `code` is then null). An item with a usable code is never named: `variantId` for it is refused as \"has_code\", with the `scanCode` to scan or type instead.\n\n**Operation id:** `packing_scan_item` — the same operation is `app.packing.scan_item({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_scan_item`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "code": { "description": "Item barcode or sku.", "type": "string", "minLength": 1 }, "variantId": { "description": "The item named instead of scanned (one with no usable code).", "type": "string", "format": "floormode-id" }, "method": { "description": "How the item was confirmed (scan, camera, typed, tap; desk for a desk caller). Omitted: scan with a code, tap without, desk for a desk caller. paper is refused.", "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "description": "A lead's single-use grant for a tap where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/set-package": { "post": { "operationId": "packing_set_package", "summary": "packing_set_package", "description": "Record the box and the weighed parcel weight of a pack job, with where the weight came from (weightSource scale, manual, api; absent = api over REST/MCP). The answer carries what this parcel should weigh (its own units at the catalog's unit weights, plus the box's empty weight; null when one unit has no weight) and the verdict (within/outside/unknown at 15 %), both computed by Floormode, never taken from the caller. Re-sending the same weight without a source, or with the manual or api source it already has, keeps its provenance; another source is a new measurement. Where the warehouse's plan asks a lead about an outside weight (packChecklist.weigh.offPolicy lead), an outside weight is saved and the weigh step waits for a lead (packing_get steps: waiting_lead; packing_fulfill answers weigh_required) until a caller holding floor.approve sends it, approvalId carries a lead's grant for exactly that weight, or a later weight is within. Clearing the weight does not clear the wait.\n\n**Operation id:** `packing_set_package` — the same operation is `app.packing.set_package({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_set_package`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "description": "A packJobs id, e.g. \"packJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "boxId": { "anyOf": [ { "type": "string", "description": "A boxes id, e.g. \"boxes_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "weightGrams": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "weightSource": { "description": "Where the weight came from; absent = manual in the app, api over REST/MCP.", "type": "string", "enum": [ "scale", "manual", "api" ] }, "scaleDriver": { "description": "The scale's driver, with scale.", "type": "string", "enum": [ "browser_hid", "printnode" ] }, "deviceLabel": { "description": "The scale's name, with scale.", "type": "string", "minLength": 1, "maxLength": 80 }, "readAtMs": { "description": "When the scale read it (epoch ms), with scale.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "stationId": { "description": "The pack station the weight was read at; ignored unless a pack station here.", "type": "string", "format": "floormode-id" }, "approvalId": { "description": "A lead's pack_weight_off grant for exactly this weight (floor_approval_grant), where the warehouse's plan asks a lead about a weight outside the tolerance.", "type": "string", "format": "floormode-id" } }, "required": [ "packJobId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/shipment-discrepancies": { "get": { "operationId": "packing_shipment_discrepancies", "summary": "packing_shipment_discrepancies", "description": "List provider-confirmed parcels whose original physical shipment remains unverified for a warehouse/item pair, including exact staging sources and disposition evidence.\n\n**Operation id:** `packing_shipment_discrepancies` — the same operation is `app.packing.shipment_discrepancies({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_shipment_discrepancies`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "variantId", "in": "query", "required": true, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/shipment-discrepancies/dispose": { "post": { "operationId": "packing_dispose_shipment_discrepancy", "summary": "packing_dispose_shipment_discrepancy", "description": "Explicitly account for every provider-confirmed unit at its original staging source: absent or physically present at a verified destination. Records local count/move corrections without inventing SHIP or changing Shopify. Writer warehouses require whole-pair physical verification before stock synchronization resumes. Read-only warehouses complete local correction without a Shopify stock write. Both retain the order replan barrier until a correlated complete Shopify order refresh has applied.\n\n**Operation id:** `packing_dispose_shipment_discrepancy` — the same operation is `app.packing.dispose_shipment_discrepancy({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_dispose_shipment_discrepancy`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "discrepancyId": { "type": "string", "description": "A shipmentPhysicalDiscrepancies id, e.g. \"shipmentPhysicalDiscrepancies_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedUpdatedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "physicallyVerified": { "type": "boolean", "const": true }, "reviewRemainingPickedGoods": { "type": "boolean" }, "parts": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "sourceBinId": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "absentQuantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "presentQuantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "destinationBinId": { "anyOf": [ { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } }, "required": [ "sourceBinId", "absentQuantity", "presentQuantity", "destinationBinId" ] } } }, "required": [ "discrepancyId", "expectedUpdatedAtMs", "physicallyVerified", "parts" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/time-summary": { "get": { "operationId": "packing_time_summary", "summary": "packing_time_summary", "description": "The team's pack time today, in one warehouse or every one, each warehouse on its own calendar day (its time zone, else UTC): parcels completed, the average from a parcel's first step record (a scan, a confirm, a package or a check) to the press that completed it, and the parcels that took longer than 30 minutes, which are counted but left out of the average; `capped` when more warehouses exist than one read takes, `deps` the warehouses read. The same count of parcels packed as dashboard_output and analytics_fulfillment_times. Earlier days are analytics_fulfillment_times'. Team totals only: no figure per person or per station.\n\n**Operation id:** `packing_time_summary` — the same operation is `app.packing.time_summary({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_time_summary`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "One warehouse; absent or null = every warehouse.", "schema": { "description": "One warehouse; absent or null = every warehouse.", "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/packing/verify": { "post": { "operationId": "packing_verify", "summary": "packing_verify", "description": "Mark a pack job verified. Rejected while any expected item is not fully scanned.\n\n**Operation id:** `packing_verify` — the same operation is `app.packing.verify({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_verify`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "packing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packJobId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "packJobId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people": { "get": { "operationId": "people_list", "summary": "people_list", "description": "List the team by name (max 100 per page, keyset cursor): one row per person, whatever they sign in with (Shopify Admin, a P&H account, a floor PIN or badge). Active people by default; status: deactivated lists the deactivated ones. attention: needs_role lists the P&H accounts WorkOS gave no Floormode role, removed the people removed from the P&H organisation. search matches part of a name, case-insensitive. The person id is what every assignee and actor field holds.\n\n**Operation id:** `people_list` — the same operation is `app.people.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "query", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "deactivated" ] } }, { "name": "attention", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "needs_role", "removed" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "people_add", "summary": "people_add", "description": "Add a person who signs in on the floor with a PIN or badge (no email, no account). The built-in Floor role by default; any other role needs team.roles. warehouseScope listed needs warehouses (each with its task types). The caller can only give what they hold.\n\n**Operation id:** `people_add` — the same operation is `app.people.add({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_add`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "warehouseScope": { "type": "string", "enum": [ "all", "listed" ] }, "warehouses": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "canDo": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } } }, "required": [ "warehouseId", "canDo" ] } } }, "required": [ "name", "warehouseScope" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/deactivate": { "post": { "operationId": "people_deactivate", "summary": "people_deactivate", "description": "Deactivate a person: every door refuses them on their next request, their floor sessions end and their PIN and badge stop working. Never oneself, never the last Admin. removeFromPlatform also removes them from the P&H organisation.\n\n**Operation id:** `people_deactivate` — the same operation is `app.people.deactivate({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_deactivate`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "removeFromPlatform": { "type": "boolean" } }, "required": [ "personId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/erase": { "post": { "operationId": "people_erase", "summary": "people_erase", "description": "Erase a deactivated person, irreversibly: their name and email disappear everywhere, their PIN, badge and invitation logins, warehouses, preferences and private views are deleted. Their Shopify and P&H login ids stay as security data and their time records until their retention ends, under a pseudonymous id.\n\n**Operation id:** `people_erase` — the same operation is `app.people.erase({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_erase`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/get": { "get": { "operationId": "people_get", "summary": "people_get", "description": "One person: name, status, where their role stands, the Floormode role or the roles their P&H account holds, whether they own the store, their warehouses and task types, their logins (kind, provider name, invitation state — never a PIN, badge or invitation link) and what the caller may do (manage, changeRole).\n\n**Operation id:** `people_get` — the same operation is `app.people.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "query", "parameters": [ { "name": "personId", "in": "query", "required": true, "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/invite": { "post": { "operationId": "people_invite", "summary": "people_invite", "description": "Invite someone to sign in with a P&H account, with a role and warehouses. An email that already belongs to a person attaches the invitation to them (attached: true). Needs the caller's own P&H account; a role other than Floor needs team.roles. WorkOS sends the invitation email; people_get shows its state.\n\n**Operation id:** `people_invite` — the same operation is `app.people.invite({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_invite`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "warehouseScope": { "type": "string", "enum": [ "all", "listed" ] }, "warehouses": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "canDo": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } } }, "required": [ "warehouseId", "canDo" ] } } }, "required": [ "email", "roleId", "warehouseScope" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/invite/resend": { "post": { "operationId": "people_invite_resend", "summary": "people_invite_resend", "description": "Send a person's P&H invitation again (a stuck, failed or expired one). WorkOS adopts an invitation it already holds for the email instead of sending a second one.\n\n**Operation id:** `people_invite_resend` — the same operation is `app.people.invite_resend({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_invite_resend`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/invite/revoke": { "post": { "operationId": "people_invite_revoke", "summary": "people_invite_revoke", "description": "Withdraw a person's open P&H invitation. The person and their other logins stay.\n\n**Operation id:** `people_invite_revoke` — the same operation is `app.people.invite_revoke({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_invite_revoke`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/me": { "get": { "operationId": "people_me", "summary": "people_me", "description": "Who the caller is: selfId (the id their own tasks, views and preferences carry), their person (null before their first change is recorded), the roles their access comes from, the permissions they hold right now, the session kind (desk, floor device, kiosk) with the floor device's warehouse and task types, and their warehouse scope. An agent never holds more than the person who connected it.\n\n**Operation id:** `people_me` — the same operation is `app.people.me({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_me`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/merge": { "post": { "operationId": "people_merge", "summary": "people_merge", "description": "Merge two people into one, irreversibly (linking a Shopify person with a P&H person is a merge). The survivor keeps its id and name; logins, warehouses, preferences, saved views and open work move to it. roleSource keep keeps roleId (written to WorkOS for a P&H person), platform uses the role the P&H membership holds. Needs team.people and team.roles and covering both people's access; never leaves the team without an Admin.\n\n**Operation id:** `people_merge` — the same operation is `app.people.merge({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_merge`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "survivorId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "mergedId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "roleSource": { "type": "string", "enum": [ "keep", "platform" ] }, "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "survivorId", "mergedId", "roleSource" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/notice/acknowledge": { "post": { "operationId": "people_notice_acknowledge", "summary": "people_notice_acknowledge", "description": "Acknowledge the co-determination and data-protection notice as an Admin: the banner goes away for everyone.\n\n**Operation id:** `people_notice_acknowledge` — the same operation is `app.people.notice_acknowledge({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_notice_acknowledge`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/notice/record": { "post": { "operationId": "people_notice_record", "summary": "people_notice_record", "description": "Acknowledge the co-determination and data-protection notice when switching on a people or labour feature for the first time (the first floor device, the time clock, the first shift pattern, the Today board, per-person output, day plans). The first call is kept; unless the caller is an Admin, every Admin then sees a banner until one acknowledges.\n\n**Operation id:** `people_notice_record` — the same operation is `app.people.notice_record({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_notice_record`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "floor_device", "time_clock", "shift_pattern", "today_board", "output", "day_plans" ] } }, "required": [ "trigger" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/platform-refresh": { "post": { "operationId": "people_requestPlatformRefresh", "summary": "people_requestPlatformRefresh", "description": "Ask Floormode to re-read the roles and memberships of the P&H account: at once while the built-in roles were never written there, else at most once per five minutes.\n\n**Operation id:** `people_requestPlatformRefresh` — the same operation is `app.people.requestPlatformRefresh({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_requestPlatformRefresh`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/reactivate": { "post": { "operationId": "people_reactivate", "summary": "people_reactivate", "description": "Reactivate a deactivated person, within the caller's own access.\n\n**Operation id:** `people_reactivate` — the same operation is `app.people.reactivate({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_reactivate`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/role": { "post": { "operationId": "people_set_role", "summary": "people_set_role", "description": "Give a person a role. Needs team.roles and the caller's own P&H account; the role and the person's current access must be within the caller's; never the caller's own role and never the last Admin's. For a person signing in with a P&H account the role is written to WorkOS (pending: true) and they keep only what both roles allow until it confirms.\n\n**Operation id:** `people_set_role` — the same operation is `app.people.set_role({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_set_role`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId", "expectedRevision", "roleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/settings": { "get": { "operationId": "people_settings_get", "summary": "people_settings_get", "description": "The team defaults: the default staff role (null = derived: Admin when every store is a development store, else Manager), PIN length, badge mode, the floor idle lock, the labour limits, the per-person output window and rankings, the time record retention and the notice acknowledgements.\n\n**Operation id:** `people_settings_get` — the same operation is `app.people.settings_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_settings_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/settings/default-role": { "post": { "operationId": "people_settings_update_default_role", "summary": "people_settings_update_default_role", "description": "Change the role Shopify staff without one get (team.roles and the caller's own P&H account; a role within the caller's own). null restores the derived default.\n\n**Operation id:** `people_settings_update_default_role` — the same operation is `app.people.settings_update_default_role({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_settings_update_default_role`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "defaultStaffRoleId": { "anyOf": [ { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } }, "required": [ "expectedRevision", "defaultStaffRoleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/settings/labour": { "post": { "operationId": "people_settings_update_labour", "summary": "people_settings_update_labour", "description": "Change the labour limits: the presence timeout and shift ceiling (labour.shifts), the per-person output window (labour.productivity; above 14 days also team.roles), rankings (labour.productivity and team.roles), the time record retention (labour.timesheets and team.roles), day plans (labour.shifts) and targets on the day plan (labour.productivity; switching them on also needs team.roles, the Elevate plan, day plans on, an output window above 0 and `confirmNotice: true`, the stronger notice confirmed in the same write — refused with plan_required, output_disabled, day_plans_off or notice_required). Per-person counts are kept only while targets are on, only for people planned for picking or packing that day, and leave after 2 days.\n\n**Operation id:** `people_settings_update_labour` — the same operation is `app.people.settings_update_labour({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_settings_update_labour`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "presenceTimeoutMs": { "type": "integer", "minimum": 60000, "maximum": 86400000 }, "maxShiftMs": { "type": "integer", "minimum": 3600000, "maximum": 86400000 }, "personOutputWindowDays": { "type": "number", "enum": [ 0, 7, 14, 30, 90 ] }, "rankingsEnabled": { "type": "boolean" }, "timeRecordRetentionMonths": { "type": "integer", "minimum": 3, "maximum": 24 }, "dayPlansEnabled": { "type": "boolean" }, "targetsEnabled": { "type": "boolean" }, "confirmNotice": { "type": "boolean" } }, "required": [ "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/settings/team": { "post": { "operationId": "people_settings_update_team", "summary": "people_settings_update_team", "description": "Change the PIN length and badge mode (team.people) and the floor idle lock default (team.devices).\n\n**Operation id:** `people_settings_update_team` — the same operation is `app.people.settings_update_team({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_settings_update_team`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pinLength": { "type": "integer", "minimum": 4, "maximum": 8 }, "badgeMode": { "type": "string", "enum": [ "badge_only", "badge_and_pin" ] }, "idleLockDefaultMs": { "type": "integer", "minimum": 120000, "maximum": 3600000 } }, "required": [ "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/unlink": { "post": { "operationId": "people_unlink", "summary": "people_unlink", "description": "Move one Shopify or P&H login off a person onto a new, deactivated person named after it. Never the caller's own login.\n\n**Operation id:** `people_unlink` — the same operation is `app.people.unlink({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_unlink`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "loginId": { "type": "string", "description": "A teamLogins id, e.g. \"teamLogins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "personId", "loginId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/people/update": { "post": { "operationId": "people_update", "summary": "people_update", "description": "Edit a person: name, contact email, warehouseScope and the warehouses with their task types. Never the caller's own warehouses; only warehouses and task types the caller holds. expectedRevision is the revision people_get returned.\n\n**Operation id:** `people_update` — the same operation is `app.people.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/people_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "people" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "warehouseScope": { "type": "string", "enum": [ "all", "listed" ] }, "warehouses": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "canDo": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } } }, "required": [ "warehouseId", "canDo" ] } } }, "required": [ "personId", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches": { "get": { "operationId": "picking_list_batches", "summary": "picking_list_batches", "description": "List pick batches, in the chosen order (`sort`; newest first by default), one page, with line and unit progress. Filter by status (open, picking, picked, cancelled), warehouse, source or the pick profile a batch was cut for (`profileId`, before the page window). `source` is the one that matters for finding SIBLING work: `assemblified_wo` returns the component batches cut for an Assemblified work order (their `sourceRef` carries the work order, and `production_pipeline` joins them to its head and its finished-goods receipt), `shopify_fo` returns customer-order picks. It is applied BEFORE the page window, so it is how a component batch stays reachable in a shop that mostly picks Shopify orders — filtering after the cap could not find one at all. zoneId keeps batches with at least one live line in that zone (a batch interleaves several orders, so it has no zone of its own); stationId narrows to the station's warehouse. Both are applied to the page window. Every row carries `claim` (mine | unclaimed | other) relative to the caller; `assignment: \"mine\"` keeps only the batches the caller may walk (theirs or nobody's) — the Floor Mode home's view.\n\n**Operation id:** `picking_list_batches` — the same operation is `app.picking.list_batches({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_list_batches`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "statuses", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "open", "picking", "picked", "cancelled" ] } } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "source", "in": "query", "required": false, "description": "shopify_fo (a customer order) or assemblified_wo (components for a work order).", "schema": { "description": "shopify_fo (a customer order) or assemblified_wo (components for a work order).", "type": "string", "enum": [ "shopify_fo", "assemblified_wo" ] } }, { "name": "zoneId", "in": "query", "required": false, "description": "Batches with live lines in this zone.", "schema": { "description": "Batches with live lines in this zone.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "profileId", "in": "query", "required": false, "description": "Only the batches cut by (or for) this pick profile.", "schema": { "description": "Only the batches cut by (or for) this pick profile.", "type": "string", "format": "floormode-id" } }, { "name": "assignment", "in": "query", "required": false, "description": "mine = the caller's or unclaimed batches; all = every batch.", "schema": { "description": "mine = the caller's or unclaimed batches; all = every batch.", "type": "string", "enum": [ "mine", "all" ] } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "picking_create_batch", "summary": "picking_create_batch", "description": "Create a pick batch (max 20 fulfillment orders). Pass foDocIds for an explicit selection or leave it out to take the queue, oldest ready order first. `profileId` cuts for a live pick profile (the Elevate plan, `plan_required` below it): the queue path takes only its orders, an explicit selection returns the orders it does not take in `skipped`, its method and order count are the defaults, and the batch records the profile. A batch takes at most `max` orders (default: the profile's order count, else 20); an explicit selection with more ready orders is refused as a conflict (`selection_too_large`), never cut short. Before the queue path reads its orders it re-plans up to ten of the warehouse's stale reservations (an expired lot, a bin no longer allocatable), so a batch never takes stock allocation would refuse today. Breaking since 2026-10-12: `filter` is removed and the input is strict — a call still sending `filter: \"singles\"` is refused as invalid_input; create a pick profile from the Singles template (units = 1) and pass its profileId. The lines of all fulfillment orders are interleaved and sorted by bin pick sequence, and the allocations move to `picking` — from then on the batch owns their reservations. Fulfillment orders that are not pickable are returned in `skipped` instead of failing the call, and eligible ones that did not fit the batch's pick-line budget come back in `deferred` — untouched, still queued, cut a second batch for them. Orders the plan allowance refuses to release come back in `admissionBlocked` — deferred, still queued, recorded on the order (`order_admission_blocked`) — and `requiredPlan` names the plan to confirm. When the allowance refuses EVERY candidate the call still answers: `pickBatchId` and `shortId` are null, nothing is batched, and the refusal records on the orders are kept — a plan refusal is an answer, not an error (A2-0053). `method: \"cluster\"` numbers a cart slot per order (WMS-045) so one walk fills several parcels — and it is the one argument here behind a PLAN GATE: cluster picking requires the Enhanced tier and is refused as `forbidden` (`plan_required`) below it, while the default `method: \"batch\"` is available on every plan. The gate is conditional on that value, which is why this operation carries no catalog-level minPlan.\n\n**Operation id:** `picking_create_batch` — the same operation is `app.picking.create_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_create_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "foDocIds": { "description": "An explicit selection; absent = the oldest ready orders of the queue.", "maxItems": 20, "type": "array", "items": { "type": "string", "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "profileId": { "description": "Only the orders this live pick profile takes, oldest first; a selection skips the rest. Its method and order count are the defaults (Elevate).", "type": "string", "format": "floormode-id" }, "max": { "description": "Orders per batch: defaults to the profile's order count, else 20. A selection with more ready orders is refused (selection_too_large), never cut short.", "type": "integer", "minimum": 1, "maximum": 20 }, "pickerId": { "description": "The person (people_list) who picks it; omitted or null puts it in the pool.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "method": { "description": "cluster assigns each order a cart slot and REQUIRES the Enhanced plan (403 `plan_required` below it); the default single/batch is available on every plan.", "type": "string", "enum": [ "batch", "cluster" ] } }, "required": [ "warehouseId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/cancel": { "post": { "operationId": "picking_cancel_batch", "summary": "picking_cancel_batch", "description": "Cancel an UNTOUCHED order pick batch (fulfillment.assign): nothing picked, nothing staged. Its pending lines are cancelled, its orders go back to the pick queue with the reservations they held, and the batch closes as cancelled. A batch with picked or staged units is refused (batch_started) — cancel or finish its orders instead. A component batch is cancelled through picking_cancel_component_batch. Cancelling a cancelled batch answers it again.\n\n**Operation id:** `picking_cancel_batch` — the same operation is `app.picking.cancel_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_cancel_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reason": { "type": "string", "maxLength": 400 } }, "required": [ "pickBatchId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/cancel-component": { "post": { "operationId": "picking_cancel_component_batch", "summary": "picking_cancel_component_batch", "description": "Cancel an Assemblified component pick batch from the floor (contracts 1.2.0). An UNTOUCHED batch (open, nothing staged) is cancelled outright; a batch with picks in it is FLAGGED instead — it keeps its status and gains an unresolved cancel request, because units are sitting in the work-order staging bin and somebody has to walk them back (picking_resolve_cancelled_component_batch). Reports wo_pick_status: cancelled to Assemblified only when that peer has been observed on contracts 1.2 — below it the value would be rejected outright, so nothing is sent. Cancelling an already-cancelled batch is a no-op.\n\n**Operation id:** `picking_cancel_component_batch` — the same operation is `app.picking.cancel_component_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_cancel_component_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reason": { "type": "string", "maxLength": 400 } }, "required": [ "pickBatchId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/complete": { "post": { "operationId": "picking_complete_batch", "summary": "picking_complete_batch", "description": "Close a pick batch once no line is pending any more and create the pack job of every fulfillment order that has picked goods. `shortLines` counts the lines that were picked short.\n\n**Operation id:** `picking_complete_batch` — the same operation is `app.picking.complete_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_complete_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "pickBatchId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/complete-component": { "post": { "operationId": "picking_complete_component_batch", "summary": "picking_complete_component_batch", "description": "Close an Assemblified component pick batch once every pickable line is resolved and report wo_pick_status (staged/short) back to the work order (INT-020). Virtual and unmapped lines never block completion. `switchedOff` is true while the Assemblified connection is switched off: nothing is sent, now or later.\n\n**Operation id:** `picking_complete_component_batch` — the same operation is `app.picking.complete_component_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_complete_component_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "pickBatchId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/confirm-as-listed": { "post": { "operationId": "picking_confirm_as_listed", "summary": "picking_confirm_as_listed", "description": "Books a pick batch walked from its printed list (roadmap C2c) where the warehouse's paperPickRecord policy is on (else conflict paper_record_off). The call books the shorts and the first lines in one transaction and answers them; a longer list's rest (`booking`: its lines and units) books in the background, a few lines a transaction, so the floor's scans run between them, and the batch completes once it is booked (conflict paper_record_booking while a list of the batch is still booking). Every line still to pick books its open quantity minus the `shorts` the caller lists (at most the line's open quantity, else invalid_input): the units move into the staging bin with their reservation exactly as a floor pick's, each line's control event records confirm paper, and a short takes the floor's short path, which may re-allocate the missing units to other bins: those `replacementLines` keep the batch open. With nothing left the batch completes and its pack jobs are created; its pick time is never measured (paper). The booking is the batch's picker's: `pickedBy` must be that picker, or, for a batch nobody holds, a person it is assigned to first (needs fulfillment.assign); the batch's timeline records who walked it and who booked it. Component batches are refused. Bound to `requestKey`: a retry answers the first result and books nothing twice; a crash between parts resumes. Irreversible.\n\n**Operation id:** `picking_confirm_as_listed` — the same operation is `app.picking.confirm_as_listed({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_confirm_as_listed`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "shorts": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "pickLineId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "pickLineId", "qty" ] }, "description": "The units the list says were missing, per pending line; [] for none." }, "pickedBy": { "description": "The person who walked the list (a team member id); omitted: the batch's picker.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One per submit, kept across retries." } }, "required": [ "pickBatchId", "shorts", "requestKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/get": { "get": { "operationId": "picking_get_batch", "summary": "picking_get_batch", "description": "Get one pick batch with its lines in walk order (bin pick sequence) and the code of the packing staging bin the picks go to.\n\n**Operation id:** `picking_get_batch` — the same operation is `app.picking.get_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_get_batch`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "pickBatchId", "in": "query", "required": true, "description": "document id of the pick batch.", "schema": { "type": "string", "description": "document id of the pick batch.", "format": "floormode-id" } }, { "name": "desk", "in": "query", "required": false, "description": "Also answer confirmSummary and pickerName, which a floor screen never shows. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Also answer confirmSummary and pickerName, which a floor screen never shows.", "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/batches/resolve-cancelled-component": { "post": { "operationId": "picking_resolve_cancelled_component_batch", "summary": "picking_resolve_cancelled_component_batch", "description": "Return the staged goods of a flagged-cancelled component pick batch to stock and close the batch (contracts 1.2.0). Every component_pick movement is walked back out of the work-order staging bin into the bin it actually came from — same variant, same lot, same quantity — with the Shopify push suppressed on both legs. Fails when the batch carries no cancel request or was already resolved.\n\n**Operation id:** `picking_resolve_cancelled_component_batch` — the same operation is `app.picking.resolve_cancelled_component_batch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_resolve_cancelled_component_batch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "pickBatchId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/component-stage-bin": { "get": { "operationId": "picking_component_stage_bin", "summary": "picking_component_stage_bin", "description": "Code of the work-order staging bin component picks go to for a warehouse (INT-020), or null if none has been created yet.\n\n**Operation id:** `picking_component_stage_bin` — the same operation is `app.picking.component_stage_bin({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_component_stage_bin`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/destination-station": { "post": { "operationId": "picking_set_destination_station", "summary": "picking_set_destination_station", "description": "Set an open pick batch's packing or production destination station. Compare-and-set prevents stale edits; stock and completed picks are unchanged.\n\n**Operation id:** `picking_set_destination_station` — the same operation is `app.picking.set_destination_station({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_set_destination_station`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickBatchId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "stationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "expectedStationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "required": [ "pickBatchId", "stationId", "expectedStationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles": { "get": { "operationId": "pick_profiles_list", "summary": "pick_profiles_list", "description": "A warehouse's pick profiles — which ready orders a picker takes and how they are batched — in tile order: name, rule, method, orders per batch, revision, and each live profile's exact `readyCount` (the orders ready for it now, the same count picking_queue with its profileId answers; null while a tag condition waits for order tags to be prepared after an update). `includeArchived` adds the newest 50 archived profiles after the live ones. Below the Elevate plan the rows still answer, with `gated: true` and no counts.\n\n**Operation id:** `pick_profiles_list` — the same operation is `app.pick.profiles_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "includeArchived", "in": "query", "required": false, "description": "Also list archived profiles (the newest 50), after the live ones. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Also list archived profiles (the newest 50), after the live ones.", "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "pick_profiles_create", "summary": "pick_profiles_create", "description": "Create a pick profile at the end of the warehouse's tiles: a name unique among its live profiles (a name_taken conflict), a rule (conditions over tag, lines and units to pick, destination country, delivery method, priority and SKU; values are normalised — countries to ISO codes, counts to whole numbers), a method and the orders per batch (single takes one). At most 12 live profiles per warehouse (a too_many_profiles conflict). A cluster profile requires the Enhanced plan; profiles require Elevate.\n\n**Operation id:** `pick_profiles_create` — the same operation is `app.pick.profiles_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `pick_profiles`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "1–60 characters; unique among the warehouse's live profiles." }, "rule": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "matchAll": { "type": "boolean", "description": "true: every condition must hold; false: any one." }, "conditions": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "tag", "lineCount", "units", "destinationCountry", "deliveryMethod", "priority", "sku" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "field", "op", "value" ], "additionalProperties": false }, "description": "At most 10. Fields and their operators: tag (in, neq = has none of, eq, contains), lineCount and units (eq, lt, gt: the lines and units to pick), destinationCountry (eq, neq, in; ISO codes or names), deliveryMethod (eq, in), priority (eq, in) and sku (eq, in, contains). A list value is comma-separated, at most 50 values." } }, "required": [ "v", "matchAll", "conditions" ], "additionalProperties": false }, "method": { "type": "string", "enum": [ "single", "batch", "cluster" ], "description": "single (one order a batch), batch, or cluster (a cart slot per order)." }, "maxOrders": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Orders per batch, 1–20; a single profile takes 1." } }, "required": [ "warehouseId", "name", "rule", "method", "maxOrders" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles/archive": { "post": { "operationId": "pick_profiles_archive", "summary": "pick_profiles_archive", "description": "Archive a pick profile: its tile leaves the floor, its name is free again and the other tiles close the gap. Batches and picker defaults keep naming it; it can be restored. Available on every plan, so a downgraded shop can retire a profile.\n\n**Operation id:** `pick_profiles_archive` — the same operation is `app.pick.profiles_archive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_archive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "profileId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles/preview": { "post": { "operationId": "pick_profiles_preview", "summary": "pick_profiles_preview", "description": "What an unsaved pick profile rule would take now: the exact count of ready orders it matches in the warehouse and the oldest three of them. Reads only; requires the Elevate plan.\n\n**Operation id:** `pick_profiles_preview` — the same operation is `app.pick.profiles_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `elevate` (feature `pick_profiles`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "rule": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "matchAll": { "type": "boolean", "description": "true: every condition must hold; false: any one." }, "conditions": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "tag", "lineCount", "units", "destinationCountry", "deliveryMethod", "priority", "sku" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "field", "op", "value" ], "additionalProperties": false }, "description": "At most 10. Fields and their operators: tag (in, neq = has none of, eq, contains), lineCount and units (eq, lt, gt: the lines and units to pick), destinationCountry (eq, neq, in; ISO codes or names), deliveryMethod (eq, in), priority (eq, in) and sku (eq, in, contains). A list value is comma-separated, at most 50 values." } }, "required": [ "v", "matchAll", "conditions" ], "additionalProperties": false } }, "required": [ "warehouseId", "rule" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles/reorder": { "post": { "operationId": "pick_profiles_reorder", "summary": "pick_profiles_reorder", "description": "Put a warehouse's live pick profiles in a new tile order. `profileIds` names every live profile exactly once; a list from a stale screen is refused as a conflict.\n\n**Operation id:** `pick_profiles_reorder` — the same operation is `app.pick.profiles_reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `pick_profiles`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "profileIds": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "description": "Every live profile of the warehouse, in the new order." } }, "required": [ "warehouseId", "profileIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles/restore": { "post": { "operationId": "pick_profiles_restore", "summary": "pick_profiles_restore", "description": "Restore an archived pick profile to the end of the tiles, if no live profile took its name (a name_taken conflict) and the warehouse has room (too_many_profiles).\n\n**Operation id:** `pick_profiles_restore` — the same operation is `app.pick.profiles_restore({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_restore`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `pick_profiles`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "profileId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/profiles/update": { "post": { "operationId": "pick_profiles_update", "summary": "pick_profiles_update", "description": "Replace a live pick profile's name, rule and recipe. Pass the revision the edit started from; a profile saved since answers revision_mismatch and changes nothing. Batches already cut keep their orders.\n\n**Operation id:** `pick_profiles_update` — the same operation is `app.pick.profiles_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pick_profiles_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `pick_profiles`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The revision the edit started from; a newer one answers revision_mismatch." }, "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "1–60 characters; unique among the warehouse's live profiles." }, "rule": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "matchAll": { "type": "boolean", "description": "true: every condition must hold; false: any one." }, "conditions": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "tag", "lineCount", "units", "destinationCountry", "deliveryMethod", "priority", "sku" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "field", "op", "value" ], "additionalProperties": false }, "description": "At most 10. Fields and their operators: tag (in, neq = has none of, eq, contains), lineCount and units (eq, lt, gt: the lines and units to pick), destinationCountry (eq, neq, in; ISO codes or names), deliveryMethod (eq, in), priority (eq, in) and sku (eq, in, contains). A list value is comma-separated, at most 50 values." } }, "required": [ "v", "matchAll", "conditions" ], "additionalProperties": false }, "method": { "type": "string", "enum": [ "single", "batch", "cluster" ], "description": "single (one order a batch), batch, or cluster (a cart slot per order)." }, "maxOrders": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Orders per batch, 1–20; a single profile takes 1." } }, "required": [ "profileId", "expectedRevision", "name", "rule", "method", "maxOrders" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/queue": { "get": { "operationId": "picking_queue", "summary": "picking_queue", "description": "Fulfillment orders ready to be picked: fully allocated (nothing short), not held, not already in a pick batch, a disclosed page at a time (`rows`/`capped`/`cursor`, max 100) oldest allocation first (`allocated:asc`, the default) or newest first. Each row carries the units, the number of bins to visit, whether it is a single (one line, one unit), when it became ready (`createdAt`) and its open pick task when the labour layer raised one. Filters are server predicates: `singles`, `assignment` (`mine` = the caller's open pick task, `unassigned` = nobody's), `lateOnly` (ready for more than a day), `zoneId` (an allocated line in that zone), `stationId` (the station's warehouse), `profileId` (the orders a live pick profile takes; the Elevate plan, `plan_required` below it). An order whose reservation went stale (an expired lot, a bin no longer allocatable) is not ready until a cut re-plans it (see picking_queue_exclusions). `readyCount` is the scope's exact total on page one. Breaking since 2026-10-06: the former single-valued filter argument is refused; pass `singles: true`. Each row's `dueAt` / `dueKind` / `packDay`: due = the end of the pack day (the warehouse's packing day before the customer's requested delivery day, in the warehouse's time zone) for work at a warehouse with a requested delivery date while delivery dates are on, else Shopify's fulfil-by (`fulfillBy` stays Shopify's raw promise).\n\n**Operation id:** `picking_queue` — the same operation is `app.picking.queue({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_queue`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Only this warehouse's queue; absent = every warehouse.", "schema": { "description": "Only this warehouse's queue; absent = every warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "zoneId", "in": "query", "required": false, "description": "Only orders with a line in this zone.", "schema": { "description": "Only orders with a line in this zone.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "singles", "in": "query", "required": false, "description": "Only single-item orders (one line, one unit). Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only single-item orders (one line, one unit).", "type": "boolean" } }, { "name": "profileId", "in": "query", "required": false, "description": "Only the orders this live pick profile takes; requires the Elevate plan (`plan_required` below it).", "schema": { "description": "Only the orders this live pick profile takes; requires the Elevate plan (`plan_required` below it).", "type": "string", "format": "floormode-id" } }, { "name": "assignment", "in": "query", "required": false, "description": "`mine` = orders whose open pick task is the caller's; `unassigned` = nobody's.", "schema": { "description": "`mine` = orders whose open pick task is the caller's; `unassigned` = nobody's.", "type": "string", "enum": [ "mine", "unassigned" ] } }, { "name": "lateOnly", "in": "query", "required": false, "description": "Only orders ready for longer than a day (the home card's late threshold). Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only orders ready for longer than a day (the home card's late threshold).", "type": "boolean" } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`allocated:asc` (oldest first, the default) or `allocated:desc`.", "schema": { "description": "`allocated:asc` (oldest first, the default) or `allocated:desc`.", "type": "string", "enum": [ "allocated:asc", "allocated:desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Orders per page (max 100).", "schema": { "description": "Orders per page (max 100).", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/queue/exclusions": { "get": { "operationId": "picking_queue_exclusions", "summary": "picking_queue_exclusions", "description": "Why orders are NOT in the pick queue: exact counts of allocations that are short of stock, stale (reserved on a lot that has expired or in a bin that is no longer allocatable — flagged by a short, archived, unsellable or frozen by a count; the next batch cut re-plans up to ten of them, or a count clears the bin), held (a Shopify hold or an open hold intent) and already owned by a pick batch, plus open fulfillment orders assigned to a Shopify location no warehouse is linked to (`unmapped`, tenant-wide). Omit warehouseId for every warehouse.\n\n**Operation id:** `picking_queue_exclusions` — the same operation is `app.picking.queue_exclusions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_queue_exclusions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/record-component-pick": { "post": { "operationId": "picking_record_component_pick", "summary": "picking_record_component_pick", "description": "Record one component pick for an Assemblified work-order batch (INT-020). Moves the goods into the work-order staging bin and suppresses the Shopify push (Assemblified adjusts the component inventory itself). `scannedBin`/`scannedVariant` are validated server-side; `short: true` records the shortfall in place without cross-bin re-allocation. Display-only VMAT lines are rejected. A required idempotencyKey identifies one pick attempt; reuse it after a lost response. Reusing a recorded key for a different line or quantity is refused.\n\n**Operation id:** `picking_record_component_pick` — the same operation is `app.picking.record_component_pick({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_record_component_pick`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickLineId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "qty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scannedBin": { "type": "string" }, "scannedVariant": { "type": "string" }, "short": { "type": "boolean" }, "note": { "type": "string" }, "confirm": { "description": "How each step was confirmed (scan, camera, typed, tap; desk for a desk planner). Omitted: desk for a caller holding fulfillment.plan outside a floor session, else scan when the step's code is sent and tap when not. paper is refused.", "type": "object", "properties": { "bin": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "item": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] } } }, "approvalIds": { "description": "A lead's single-use grants (floor approvals), one per gated action of the call: short_line for a short, confirm_without_scan for a tap where the warehouse confirms by scan only. A tapped short carries both.", "maxItems": 2, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } }, "required": [ "pickLineId", "idempotencyKey", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/record-pick": { "post": { "operationId": "picking_record_pick", "summary": "picking_record_pick", "description": "Record one pick. `scannedBin`/`scannedVariant` are validated against the line (a tapped step names it by construction; `confirm` says how each step was confirmed, and where the warehouse confirms by scan only a tapped step is refused as {ok: false, refused: \"scan_required\", step} unless a lead approved it) server-side — a wrong scan returns {ok: false, mismatch: \"bin\"|\"item\", verdict: \"unknown\"|\"wrong_target\"|\"ambiguous\"} and changes nothing (unknown = nothing answers to the code; wrong_target = a real bin/item, not this line's). A successful pick moves the goods into the packing staging bin AND carries their reservation along. `short: true` reports the bin as exhausted: the missing quantity is re-allocated from other pickable bins (returned in `reallocated`) and whatever no bin can cover becomes `shortQty`, which also flags the source bin as a problem. A line naming a LOCAL item (a sub-assembly inside a kit) is refused with a coded `details.localRefusal` — `local_stock_frozen`, `item_unplaced`, `catalog_unconfirmed` — and never a zero-quantity success, which would be indistinguishable from a genuine short pick.\n\n**Operation id:** `picking_record_pick` — the same operation is `app.picking.record_pick({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_record_pick`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickLineId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "qty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scannedBin": { "description": "Bin code or barcode the picker scanned.", "type": "string" }, "scannedVariant": { "description": "Item barcode or sku the picker scanned.", "type": "string" }, "short": { "type": "boolean" }, "note": { "description": "Reason recorded on the bin problem flag.", "type": "string" }, "idempotencyKey": { "description": "Caller-minted key per attempt. A replay answers the line's current state with `replayed: true` instead of booking the units again.", "type": "string", "minLength": 1, "maxLength": 200 }, "confirm": { "description": "How each step was confirmed (scan, camera, typed, tap; desk for a desk planner). Omitted: desk for a caller holding fulfillment.plan outside a floor session, else scan when the step's code is sent and tap when not. paper is refused.", "type": "object", "properties": { "bin": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "item": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] } } }, "approvalIds": { "description": "A lead's single-use grants (floor approvals), one per gated action of the call: short_line for a short, confirm_without_scan for a tap where the warehouse confirms by scan only. A tapped short carries both.", "maxItems": 2, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } }, "required": [ "pickLineId", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/picking/route-preview": { "get": { "operationId": "picking_route_preview", "summary": "picking_route_preview", "description": "Preview the first 24 remaining physical stops in their existing pick order. Completed picks are untouched; partial or unresolved routes disclose their bounds.\n\n**Operation id:** `picking_route_preview` — the same operation is `app.picking.route_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/picking_route_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "picking" ], "x-operation-kind": "query", "parameters": [ { "name": "batchId", "in": "query", "required": true, "description": "A pickBatches id, e.g. \"pickBatches_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A pickBatches id, e.g. \"pickBatches_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "profile", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "walk", "cart" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/pickups": { "get": { "operationId": "pickups_list", "summary": "pickups_list", "description": "List carrier pickups, newest first (max 100), with the warehouse and carrier label. Filter by status (scheduling, scheduled, confirmed, cancelled), warehouse or carrier account.\n\n**Operation id:** `pickups_list` — the same operation is `app.pickups.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pickups_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "pickups" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduling", "scheduled", "confirmed", "cancelled" ] } }, { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "carrierAccountId", "in": "query", "required": false, "description": "document id of the carrier account.", "schema": { "description": "document id of the carrier account.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/pickups/resolve": { "post": { "operationId": "pickups_resolve", "summary": "pickups_resolve", "description": "Resolve an outstanding carrier pickup booking whose answer nobody could read: `booked` records the collection on the operator's attestation (with the carrier's confirmation number when known), `not_booked` cancels the attempt so a new booking can be made. Refused while the attempt is still running, and `not_booked` is refused when the carrier's answer is held.\n\n**Operation id:** `pickups_resolve` — the same operation is `app.pickups.resolve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/pickups_resolve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "pickups" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickupId": { "type": "string", "description": "A pickups id, e.g. \"pickups_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "verdict": { "type": "string", "enum": [ "booked", "not_booked" ] }, "confirmationNumber": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "pickupId", "verdict" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/print-jobs": { "get": { "operationId": "print_jobs_list", "summary": "print_jobs_list", "description": "List cloud print jobs, newest first (max 100), with the shipment short id. Filter by shipment or by status (queued, sent, failed, unknown). Unknown means provider acceptance could not be confirmed.\n\n**Operation id:** `print_jobs_list` — the same operation is `app.print.jobs_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/print_jobs_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "print-jobs" ], "x-operation-kind": "query", "parameters": [ { "name": "shipmentId", "in": "query", "required": false, "description": "document id of the shipment.", "schema": { "description": "document id of the shipment.", "type": "string", "format": "floormode-id" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "sent", "failed", "unknown" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/print-jobs/label-attempt": { "get": { "operationId": "label_print_attempt", "summary": "label_print_attempt", "description": "Inspect one generated-label print attempt, including immutable request identity and confirmed provider acceptance. Does not expose PDF bytes or credentials.\n\n**Operation id:** `label_print_attempt` — the same operation is `app.label.print_attempt({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/label_print_attempt`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "print-jobs" ], "x-operation-kind": "query", "parameters": [ { "name": "requestKey", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/printers": { "get": { "operationId": "printers_list", "summary": "printers_list", "description": "List the tenant's discovered PrintNode printers (max 200): id, name, state, computer and the default flag. Refreshed by the Worker's printer-discovery route; the API key is never returned.\n\n**Operation id:** `printers_list` — the same operation is `app.printers.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/printers_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "printers" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/privacy/requests": { "get": { "operationId": "privacy_list", "summary": "privacy_list", "description": "List customer privacy requests, oldest first, with 50-row pagination and delivery deadlines.\n\n**Operation id:** `privacy_list` — the same operation is `app.privacy.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/privacy_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "privacy" ], "x-operation-kind": "query", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "exporting", "ready", "completed", "redacted" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/privacy/requests/confirm-delivered": { "post": { "operationId": "privacy_confirmDelivered", "summary": "privacy_confirmDelivered", "description": "Confirm that the complete retrieved export was reviewed and securely delivered to the merchant, including manual-review items. An incomplete export cannot be completed.\n\n**Operation id:** `privacy_confirmDelivered` — the same operation is `app.privacy.confirmDelivered({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/privacy_confirmDelivered`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "privacy" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 128, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "manualReviewConfirmed": { "type": "boolean", "const": true } }, "required": [ "requestId", "sessionId", "manualReviewConfirmed" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/privacy/requests/export/page": { "post": { "operationId": "privacy_exportPage", "summary": "privacy_exportPage", "description": "Retrieve the next bounded page of an authorized export and advance its session cursor. Continue until nextCursor is null; review all manual-review notices.\n\n**Operation id:** `privacy_exportPage` — the same operation is `app.privacy.exportPage({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/privacy_exportPage`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "privacy" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 128, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "cursor": { "anyOf": [ { "type": "object", "properties": { "tableIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "afterId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "tables": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "tableIndex", "afterId", "tables" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "requestId", "sessionId", "cursor" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/privacy/requests/export/start": { "post": { "operationId": "privacy_startExport", "summary": "privacy_startExport", "description": "Start or restart a complete customer-data export session. Does not fulfill the privacy request.\n\n**Operation id:** `privacy_startExport` — the same operation is `app.privacy.startExport({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/privacy_startExport`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "privacy" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "A privacyRequests id, e.g. \"privacyRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "requestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/production/pipeline": { "get": { "operationId": "production_pipeline", "summary": "production_pipeline", "description": "The PRODUCTION PIPELINE: one row per Assemblified work order, joining the three documents Floormode holds about it — the work-order head Assemblified pushes, the component pick batch cut for its materials, and the finished-goods receipt its output is put away against. Answers 'where does WO-2031 actually stand' without three separate list calls. `stage` is DERIVED on every read, never stored: announced → picking → staged → in_production → awaiting_putaway → put_away, plus cancelled. Latest evidence wins, because a document that exists proves the stages before it happened. `in_production` is the ONE stage that needs the head (only Assemblified knows the build started); every other stage is derivable from our own documents, so a shop whose peer predates contracts 1.2 still gets a working board. `status` is Assemblified's own lifecycle value and is null without a head — it sits ALONGSIDE the stage rather than being folded into it (paused, quality_control and in_progress are one stage here and three different facts there). `dueDate` is verbatim as the peer stated it: a calendar day or a full timestamp, never normalised. `shortLines` counts component lines the floor could not fully pick and `cancelPending` flags an open 'return these goods to stock' claim — both are blockers, not stages. `hasHeads: false` with no rows means this shop has no Assemblified connection rather than no work in flight. `stages` is a SET applied before every source read's cut (B12-5): absent = the whole board, finished work included; the in-flight board is every stage but put_away and cancelled. The former `stage` and `openOnly` arguments are refused. The board is ONE bounded page in soonest-due order: there is no cursor, and `capped: true` says the page is a part of the pipeline.\n\n**Operation id:** `production_pipeline` — the same operation is `app.production.pipeline({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/production_pipeline`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "production" ], "x-operation-kind": "query", "parameters": [ { "name": "stages", "in": "query", "required": false, "description": "Work orders at any of these stages; absent = every stage, finished ones too. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Work orders at any of these stages; absent = every stage, finished ones too.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "announced", "picking", "staged", "in_production", "awaiting_putaway", "put_away", "cancelled" ] } } }, { "name": "limit", "in": "query", "required": false, "description": "Work orders on the board (max 100). Default 100.", "schema": { "description": "Work orders on the board (max 100). Default 100.", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/products": { "get": { "operationId": "products_list", "summary": "products_list", "description": "List the mirrored Shopify products of the authenticated tenant (max 100).\n\n**Operation id:** `products_list` — the same operation is `app.products.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/products_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "products" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/products/refresh": { "post": { "operationId": "products_refresh", "summary": "products_refresh", "description": "Queue an authoritative Shopify snapshot for this variant's product. Requests coalesce per product and use canonical durable ingest; local items and deleted products are refused.\n\n**Operation id:** `products_refresh` — the same operation is `app.products.refresh({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/products_refresh`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "products" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "variantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/products/refresh-status": { "get": { "operationId": "products_refresh_status", "summary": "products_refresh_status", "description": "Read targeted catalog refresh delivery and canonical ingest progress. A processed snapshot can be unchanged or stale; it never means every field changed.\n\n**Operation id:** `products_refresh_status` — the same operation is `app.products.refresh_status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/products_refresh_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "products" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving": { "get": { "operationId": "receiving_list", "summary": "receiving_list", "description": "List receipts in the chosen order (`sort`; newest first by default), paged by `cursor` (at most `limit` rows), with expected/received units and the discrepancy count. Filter by one or more statuses (expected, receiving, received, cancelled), `openOnly` (expected + receiving in one call — pass either this or `status`, not both), source, warehouse, or variant. `source` names the SIBLING DOCUMENT the receipt came from: `logistified_po` (a Logistified purchase order), `logistified_to` (a Logistified transfer, the only kind `receiving_confirm_transfer_shipment` accepts), `assemblified_wo` (finished goods from an Assemblified work order) or `manual` (entered here). `warehouse_transfer` marks the receiving half of a native warehouse transfer: listed and filterable here, but received on the transfer (receiving_record_line, receiving_complete and receiving_cancel refuse it). It is applied BEFORE the page window, so it is how a sibling document stays reachable past that window — filtering after the cap could not find one at all. variantId returns only receipts carrying a line for that variant, which is the inbound history of one sku and the way to turn an `incoming` number back into documents. A receipt carries no bin and no station (putaway destinations live in the ledger), so zoneId and stationId both narrow to their WAREHOUSE — the finest granularity this surface has. `stage` keeps only receipts with units still on the dock: `inspecting` (waiting for inspection) or `putting_away` (waiting for put-away). For 'what is due, and what is late', use `receiving_schedule` instead: this list is ordered by announcement date, which is not the delivery calendar.\n\n**Operation id:** `receiving_list` — the same operation is `app.receiving.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of these statuses. Not combinable with openOnly. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses. Not combinable with openOnly.", "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "expected", "receiving", "received", "cancelled" ] } } }, { "name": "openOnly", "in": "query", "required": false, "description": "Live documents only (expected + receiving). Not combinable with status. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Live documents only (expected + receiving). Not combinable with status.", "type": "boolean" } }, { "name": "source", "in": "query", "required": false, "description": "Where the document came from: manual, warehouse_transfer, logistified_po, logistified_to, assemblified_wo.", "schema": { "description": "Where the document came from: manual, warehouse_transfer, logistified_po, logistified_to, assemblified_wo.", "type": "string", "enum": [ "manual", "warehouse_transfer", "logistified_po", "logistified_to", "assemblified_wo" ] } }, { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "stage", "in": "query", "required": false, "description": "Only receipts with units still on the dock: inspecting (waiting for inspection) or putting_away (waiting for put-away).", "schema": { "description": "Only receipts with units still on the dock: inspecting (waiting for inspection) or putting_away (waiting for put-away).", "type": "string", "enum": [ "inspecting", "putting_away" ] } }, { "name": "variantId", "in": "query", "required": false, "description": "Only receipts with a line for this variant (its inbound history).", "schema": { "description": "Only receipts with a line for this variant (its inbound history).", "type": "string", "format": "floormode-id" } }, { "name": "zoneId", "in": "query", "required": false, "description": "Narrows to the zone's warehouse.", "schema": { "description": "Narrows to the zone's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "assignment", "in": "query", "required": false, "description": "mine = assigned to the caller or to nobody; all = everyone's.", "schema": { "description": "mine = assigned to the caller or to nobody; all = everyone's.", "type": "string", "enum": [ "mine", "all" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's cursor, under the same sort.", "schema": { "description": "The previous page's cursor, under the same sort.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default), `created:asc` (oldest first), `promised:asc` (soonest promised delivery first, unscheduled last) or `promised:desc` (latest promise first, unscheduled first).", "schema": { "description": "`created:desc` (newest first, the default), `created:asc` (oldest first), `promised:asc` (soonest promised delivery first, unscheduled last) or `promised:desc` (latest promise first, unscheduled first).", "type": "string", "enum": [ "created:desc", "created:asc", "promised:asc", "promised:desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 100.", "schema": { "description": "Rows per page, at most 100.", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "receiving_create", "summary": "receiving_create", "description": "Create an expected receipt (`#RC-…`, max 500 lines). Lines are {variantId|sku, expectedQty}; duplicates of the same variant and lot are merged (one line per variant and lot; a lot-less line stays its own). A lot announced for an item that tracks no lots is refused (`details.code: \"lot_not_tracked\"`). `blind: true` opens a receipt without expectations — the floor may then receive any item, and the over-receipt tolerance is not applied. `requestKey` is minted by the caller once per submit and kept across retries: the same key with the same arguments answers the same receipt again (`replayed: true`, nothing written); the same key with other arguments is refused as a conflict (`idempotency_key_reused`). Reordered, re-split or whitespace-equivalent lines are the same arguments. The answer is kept for as long as the tenant's data, so a retry replays regardless of its age.\n\n**Operation id:** `receiving_create` — the same operation is `app.receiving.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "blind": { "type": "boolean" }, "notes": { "type": "string" }, "sourceRef": { "description": "Deep-link data of the source document (PO/TO).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "number", "name" ] }, { "type": "null" } ] }, "lines": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "sku": { "description": "Sku or barcode.", "type": "string" }, "expectedQty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "lotNumber": { "description": "Announced lot; pre-fills the receiving station.", "type": "string" }, "expiryDate": { "description": "ISO calendar day (2027-03-31), only with a lot number.", "type": "string" } }, "required": [ "expectedQty" ] } } }, "required": [ "warehouseId", "requestKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/cancel": { "post": { "operationId": "receiving_cancel", "summary": "receiving_cancel", "description": "Cancel a receipt that has not received anything yet. A receipt with goods in a bin must be completed — the ledger is append-only. A Logistified purchase- or transfer-order receipt tells Logistified it was cancelled (its one terminal report, head `cancelled`); `sourceSwitchedOff` is true when the connection is off, so Logistified was not told. The document itself stays open in Logistified. A blind delivery linked to a document is refused (`linked_receipt`): it is completed instead.\n\n**Operation id:** `receiving_cancel` — the same operation is `app.receiving.cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reason": { "type": "string" } }, "required": [ "receiptId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/complete": { "post": { "operationId": "receiving_complete", "summary": "receiving_complete", "description": "Close a receipt. Partial receipts are allowed: the remainder stays visible as a discrepancy instead of rewriting the expectation, and the discrepancy list is returned. Closing with lines still owed is a gated floor exception (close_receipt_short): outside a desk lead it needs a lead's approvalId.\n\n**Operation id:** `receiving_complete` — the same operation is `app.receiving.complete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_complete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "approvalId": { "description": "A lead's single-use grant for close_receipt_short.", "type": "string", "format": "floormode-id" } }, "required": [ "receiptId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/confirm-transfer-shipment": { "post": { "operationId": "receiving_confirm_transfer_shipment", "summary": "receiving_confirm_transfer_shipment", "description": "Confirm that the outbound leg of a transfer order left this shop's source warehouse and report it to Logistified (`to_ship_report`). Addressed by the expected receipt the transfer's inbound notice created — that receipt is the transfer order here — and refused unless the transfer ships FROM a warehouse this shop manages. The report is a status signal: it carries no quantities, moves no stock, and the Shopify write for this leg stays on the Logistified side. Confirming twice is a no-op.\n\n**Operation id:** `receiving_confirm_transfer_shipment` — the same operation is `app.receiving.confirm_transfer_shipment({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_confirm_transfer_shipment`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "shippedAt": { "description": "ISO-8601 timestamp with an offset; defaults to now.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "receiptId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/generate-serials": { "post": { "operationId": "receiving_generate_serials", "summary": "receiving_generate_serials", "description": "Generate serials for units a merchant labels themselves: books `count` units of a receipt line's item, each with the next serial of a range — `prefix`, then the number from `from`, zero-padded to the range's widest number — exactly as receiving_record_line books a scanned carton (same bin, flow, over-receipt and serial checks; all or nothing). Only for an item that records its serials at receiving. Answers like receiving_record_line, with the new units in serialUnitIds for their labels.\n\n**Operation id:** `receiving_generate_serials` — the same operation is `app.receiving.generate_serials({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_generate_serials`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptLineId": { "type": "string", "description": "The receipt line whose item the units are of.", "format": "floormode-id" }, "prefix": { "type": "string", "maxLength": 32, "description": "What every serial starts with (\"SN-2026-\"); may be empty." }, "from": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The first number of the range." }, "count": { "type": "integer", "minimum": 1, "maximum": 500, "description": "How many units are booked, each with the next serial of the range." }, "toBinId": { "description": "The bin the units go to; omitted → the suggested putaway bin (or the dock).", "type": "string", "format": "floormode-id" }, "toBinCode": { "description": "The bin by its code, as typed, when no id was chosen; ignored beside toBinId.", "type": "string", "minLength": 1 }, "idempotencyKey": { "description": "One per booking, kept across its retries; bound to the whole request.", "type": "string" } }, "required": [ "receiptLineId", "prefix", "from", "count" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/get": { "get": { "operationId": "receiving_get", "summary": "receiving_get", "description": "Get one receipt: the header totals (expected/received units, discrepancy and short-line counts, `fullyReceived`) computed over EVERY line, the FIRST page of lines (up to 100), the discrepancy list and the putaway movements this receipt produced. A receipt may hold up to 500 lines: when `hasMoreLines` is true, continue with `receiving_lines_list` using `linesCursor`. The header numbers are never a function of the page.\n\n**Operation id:** `receiving_get` — the same operation is `app.receiving.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": true, "description": "document id of the receipt.", "schema": { "type": "string", "description": "document id of the receipt.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/inspect-line": { "post": { "operationId": "receiving_inspect_line", "summary": "receiving_inspect_line", "description": "Inspect units a dock_inspect warehouse accepted into QC-IN-01: pass some (moved to DOCK-01, where a put-away task picks them up) and reject some (moved to HOSP-01 for damaged or packaging, else QUAR-01). Judged per receipt line's item and lot: more than the units still waiting is refused (`details.code: \"inspection_exceeds_received\"`). A reject needs a reason (`other` also a note); a warehouse whose inspection.photoOnFail is on (the default) also needs `photoId` (`details.code: \"photo_required\"`), the id the photo upload route answered within the last hour. Never changes the received quantity a connected app is told. Repeating the same idempotencyKey with the same verdict answers the first verdict with `replayed: true`; with another verdict it is refused.\n\n**Operation id:** `receiving_inspect_line` — the same operation is `app.receiving.inspect_line({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_inspect_line`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "description": "A receipts id, e.g. \"receipts_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "receiptLineId": { "type": "string", "description": "A receiptLines id, e.g. \"receiptLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "lotId": { "anyOf": [ { "type": "string", "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ], "description": "The lot the units carry; null for none." }, "passQty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejectQty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "description": "Required with a reject; other also needs a note.", "type": "string", "enum": [ "damaged", "wrong_item", "expired", "packaging", "other" ] }, "customReasonKey": { "description": "One of the warehouse's own inspection reasons, by key.", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "note": { "type": "string", "maxLength": 500 }, "photoId": { "description": "A photo of this receipt the photo upload route stored.", "type": "string", "format": "floormode-id" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "receiptId", "receiptLineId", "lotId", "passQty", "rejectQty", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/inspect-queue": { "get": { "operationId": "receiving_inspect_queue", "summary": "receiving_inspect_queue", "description": "The receipts with units waiting for inspection, oldest first, with the units still waiting. warehouseId, zoneId or stationId narrow it to that warehouse.\n\n**Operation id:** `receiving_inspect_queue` — the same operation is `app.receiving.inspect_queue({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_inspect_queue`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "zoneId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "stationId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/inspection-groups": { "get": { "operationId": "receiving_inspection_groups", "summary": "receiving_inspection_groups", "description": "One receipt's items and lots with units still waiting for inspection at QC-IN-01: the line a verdict names, the lot, the units waiting, and the warehouse's inspection rules (whether a fail needs a photo, its own reasons).\n\n**Operation id:** `receiving_inspection_groups` — the same operation is `app.receiving.inspection_groups({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_inspection_groups`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/inspections": { "get": { "operationId": "receiving_inspections_list", "summary": "receiving_inspections_list", "description": "One receipt's inspection verdicts, newest first, paged by `cursor`: item, lot, units passed and rejected, the reason, the bin the rejected units went to, the photo id and who inspected.\n\n**Operation id:** `receiving_inspections_list` — the same operation is `app.receiving.inspections_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_inspections_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/label-items": { "get": { "operationId": "receiving_label_items", "summary": "receiving_label_items", "description": "Read actual booked receipt movements for contextual labels, including the captured lot and expiry and current catalog price. Browse bounded pages or supply up to 200 movement ids; selected ids must all belong to this receipt.\n\n**Operation id:** `receiving_label_items` — the same operation is `app.receiving.label_items({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_label_items`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": true, "description": "A receipts id, e.g. \"receipts_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A receipts id, e.g. \"receipts_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "movementIds", "in": "query", "required": false, "description": "Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "description": "A stockMovements id, e.g. \"stockMovements_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/lines": { "get": { "operationId": "receiving_lines_list", "summary": "receiving_lines_list", "description": "One page of a receipt's expectation lines (max 100), ordered by position. Keyset pagination: pass the previous page's `cursor` back to continue, and stop when it comes back null. This is the only complete way to read the lines of a large receipt — a receipt holds up to 500 of them.\n\n**Operation id:** `receiving_lines_list` — the same operation is `app.receiving.lines_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_lines_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": true, "description": "document id of the receipt.", "schema": { "type": "string", "description": "document id of the receipt.", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "description": "`cursor` of the previous page; omit for the first.", "schema": { "description": "`cursor` of the previous page; omit for the first.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "lines per page, 1…100.", "schema": { "description": "lines per page, 1…100.", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/link-document": { "post": { "operationId": "receiving_link_document", "summary": "receiving_link_document", "description": "Link a blind receipt (counted with no document) to an open purchase order or an expected manual receipt in the same warehouse. Lines match by item, the document's oldest open line first; units beyond what the document still expects stay on its last line (an over-delivery, never refused); an item the document does not carry stays a blind line. Permanent: there is no unlink, and the linked receipt cannot be cancelled. `expectedMatchedUnits` must equal the units the link binds now, else `plan_changed` (its `matchedUnits` detail says the current count); an `expectedPlanDigest` (the app's preview) refuses it when any split or over-delivery moved too. A Logistified purchase order hears the delivery as one more split delivery: its report when the receipt is received, else its progress. Refusals: other_warehouse, document_closed, nothing_matches, already_linked, not_blind, ownership_superseded, document_receipts_full, delivery_archived (a delivery more than two years old is in the history books). `requestKey` makes a retry answer the first result.\n\n**Operation id:** `receiving_link_document` — the same operation is `app.receiving.link_document({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_link_document`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "const": "receipt" }, "receiptId": { "type": "string", "description": "A receipt of the purchase order or the expected delivery.", "format": "floormode-id" } }, "required": [ "kind", "receiptId" ] }, "expectedMatchedUnits": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "expectedPlanDigest": { "type": "string", "minLength": 1, "maxLength": 128 }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "receiptId", "target", "expectedMatchedUnits" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/plan-putaway": { "get": { "operationId": "receiving_plan_putaway", "summary": "receiving_plan_putaway", "description": "Directed putaway v1 (WHT-006): the capacity-capped split PLAN for a quantity. Ranks home location → consolidation (bins already holding the SKU) → emptiest bins, caps each leg at its remaining capacity and spills into further locations when the receipt exceeds one bin. `steps` carries the per-bin qty + reason + remaining; `capped` flags a quantity no location could take (the intrinsic over-fill guard). With no capacity configured a single unbounded step absorbs the whole quantity — today's behavior.\n\n**Operation id:** `receiving_plan_putaway` — the same operation is `app.receiving.plan_putaway({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_plan_putaway`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": false, "description": "Supplies the warehouse.", "schema": { "description": "Supplies the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "variantId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "scannedCode", "in": "query", "required": false, "description": "Item barcode or sku.", "schema": { "description": "Item barcode or sku.", "type": "string" } }, { "name": "qty", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "zone", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "seed", "in": "query", "required": false, "description": "A booking or planning key; the spread strategy ranks bins by it, so a replay proposes the same bin.", "schema": { "description": "A booking or planning key; the spread strategy ranks bins by it, so a replay proposes the same bin.", "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/record-line": { "post": { "operationId": "receiving_record_line", "summary": "receiving_record_line", "description": "Receive goods against a receipt. The item comes from variantId or scannedCode (resolved server-side through the scan router), the destination from toBinId/toBinCode or — when both are omitted — the suggested putaway bin. Writes one `receipt` ledger movement. An over-receipt beyond the warehouse's overReceiptTolerancePct is rejected; items that are not expected are only accepted on a blind receipt. Lots follow the ITEM's tracking mode (variants_set_tracking): an item that tracks lots needs one (`details.code: \"lot_required\"`; with a date when the item requires one, `expiry_required`); an item that tracks none refuses a typed lot (`lot_not_tracked`) and books a lot from a GS1 barcode or the announcement without it. A typed lot wins; otherwise the one lot still expected for the item is used (two expected lots refuse a lot-less scan of a lot item with `lot_required`); units fill the lines of their lot, then the item's lot-less lines, never another lot's; an undeclared lot becomes its own zero-expected line. The movement records where its lot came from (gs1, typed, announced). The over-receipt tolerance is judged per item over all its lines. Booking a lot item without a lot into a bin that already holds lot-tracked units of it is refused with `details.code: \"lot_required\"` and writes nothing. In a warehouse whose receiving flow is `dock` or `dock_inspect` (warehouses_update settings.receivingFlow), a manual receipt or a Logistified purchase order books into DOCK-01 (a put-away task is created or topped up) or QC-IN-01 (the units wait for receiving_inspect_line): the bin is forced, so toBinId / toBinCode are refused with `details.code: \"bin_not_used_in_dock_flow\"`. The answer's `receivingFlow` and `binCode` say where the units went. An item that records its serials at receiving (serialCapture receive) names one serial per unit in `serials` (or, for one unit, the GS1 code's serial, AI 21): each becomes a serial unit in stock in this warehouse, listed in the answer's serialUnitIds; fewer is refused as serials_needed, a unit already in stock as serial_in_stock (with its warehouse), a shipped one as serial_shipped (it comes back on its return). `partialOf` books a partial carton: the scanned units only; on the floor it takes a lead's grant (approvalId, action receive_partial).\n\n**Operation id:** `receiving_record_line` — the same operation is `app.receiving.record_line({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_record_line`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedCode": { "description": "Item barcode or sku.", "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "toBinId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "toBinCode": { "type": "string" }, "lotNumber": { "description": "Batch/lot of the goods in hand, judged by the item's tracking mode; omitted, the one lot still expected for the item is used; two expected lots refuse the scan of a lot item (`lot_required`).", "type": "string" }, "expiryDate": { "description": "ISO calendar day the lot expires on; only together with a lot number.", "type": "string" }, "idempotencyKey": { "description": "Bound to the whole booking request (item, quantity, bin, lot, expiry): repeating a key for the SAME booking writes nothing and answers the original booking with `replayed: true`; reusing it for a different booking is a conflict (`idempotency_key_reused`) that names what the key booked.", "type": "string" }, "method": { "description": "How the item was confirmed (scan, camera, typed, tap; desk for a desk caller). Omitted: scan with a code, tap without, desk for a desk caller. paper is refused.", "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "description": "A lead's single-use grant for a tap where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" }, "serials": { "description": "One serial per unit, for an item that records its serials at receiving; a GS1 code's serial (AI 21) is read out.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "partialOf": { "description": "The carton's units when fewer were scanned: the scanned units are booked.", "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, "serialMethod": { "description": "How the serials were captured: scan (the floor's default) or typed.", "type": "string", "enum": [ "scan", "typed" ] }, "typedSerials": { "description": "The serials of `serials` that were typed (the others scanned): each unit records its own method, and a lead's grant covers the typed ones alone.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "serialApprovalId": { "description": "A lead's single-use grant (serial_typed) for typed serials on the floor where the warehouse confirms by scan only; it names the receipt and the typed units.", "type": "string", "format": "floormode-id" } }, "required": [ "receiptId", "qty" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/resolve-document": { "get": { "operationId": "receiving_resolve_document", "summary": "receiving_resolve_document", "description": "Resolve a hold's covering document (`linkRef`) to the receipt that represents it here, or null when no receipt exists for it. `kind` is the link kind — `po` and `to` are Logistified documents, `wo` is an Assemblified work order, and `bom` always answers null because a bill of materials is a recipe, not something goods are received against. `ref` may be the peer's internal id, the document number or its display name: a hold can be filed from any of the three, and all three are matched, newest document first. This is the read behind 'the order is waiting for PO-1042 — show me PO-1042'.\n\n**Operation id:** `receiving_resolve_document` — the same operation is `app.receiving.resolve_document({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_resolve_document`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "kind", "in": "query", "required": true, "description": "The hold link kind.", "schema": { "type": "string", "enum": [ "po", "to", "wo", "bom" ], "description": "The hold link kind." } }, { "name": "ref", "in": "query", "required": true, "description": "The document id, number or name the hold named.", "schema": { "type": "string", "minLength": 1, "description": "The document id, number or name the hold named." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/schedule": { "get": { "operationId": "receiving_schedule", "summary": "receiving_schedule", "description": "The inbound DELIVERY CALENDAR: every open receipt (expected + receiving) in promise order, soonest first. This is the ETA view — `receiving_list` orders by announcement date, which answers a different question. `expectedAt` is epoch ms: the EARLIEST `expectedDeliveryDate` still live on one of the receipt's lines, maintained on the header as the sibling notice and its revisions write those lines. A receipt is due when its first unit is due. `expectedAt: null` means UNSCHEDULED and is returned LAST, newest first — a manual receipt, a peer on contracts 1.0 that sends no dates, or a receipt announced before this field existed. It is never guessed. Overdue is deliberately NOT computed here: 'promised before today' is a question about a calendar day in the merchant's timezone, which this server does not know. `expectedDay` (YYYY-MM-DD) is set when that earliest promise is a bare calendar day with no time: `expectedAt` is then only its UTC midnight, the sort key, so compare `expectedDay` against your own calendar day (overdue once it lies before today) and compare `expectedAt` against your own clock only when `expectedDay` is null. `capped` means either half hit the row limit and this calendar is a page of the calendar, not all of it.\n\n**Operation id:** `receiving_schedule` — the same operation is `app.receiving.schedule({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_schedule`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "source", "in": "query", "required": false, "description": "Where the document came from: manual, warehouse_transfer, logistified_po, logistified_to, assemblified_wo.", "schema": { "description": "Where the document came from: manual, warehouse_transfer, logistified_po, logistified_to, assemblified_wo.", "type": "string", "enum": [ "manual", "warehouse_transfer", "logistified_po", "logistified_to", "assemblified_wo" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per half (scheduled, unscheduled); 1…100, default 100.", "schema": { "description": "Rows per half (scheduled, unscheduled); 1…100, default 100.", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/station": { "post": { "operationId": "receiving_set_station", "summary": "receiving_set_station", "description": "Set the actual receiving station on an open receipt. Same-warehouse active receiving stations only; does not move or receive stock.\n\n**Operation id:** `receiving_set_station` — the same operation is `app.receiving.set_station({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_set_station`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "stationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "expectedStationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "required": [ "receiptId", "stationId", "expectedStationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/receiving/suggest-putaway": { "get": { "operationId": "receiving_suggest_putaway", "summary": "receiving_suggest_putaway", "description": "Directed putaway (WMS-032): the bin an item should go to. Order — the bin that already holds the variant (its de-facto home bin), else the emptiest pickable bin (optionally inside one zone), else a receiving bin. Answers {kind: \"suggested\", binId, binCode, zone, reason, holdsLots} or {kind: \"none\"} when the warehouse has no usable bin — an explicit fact, never a null. `holdsLots` says the bin already holds lot-tracked units of the item: for an item that tracks lots, a receipt into it without a lot is refused (`lot_required`).\n\n**Operation id:** `receiving_suggest_putaway` — the same operation is `app.receiving.suggest_putaway({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/receiving_suggest_putaway`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "receiving" ], "x-operation-kind": "query", "parameters": [ { "name": "receiptId", "in": "query", "required": false, "description": "Supplies the warehouse.", "schema": { "description": "Supplies the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "variantId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "scannedCode", "in": "query", "required": false, "description": "Item barcode or sku.", "schema": { "description": "Item barcode or sku.", "type": "string" } }, { "name": "zone", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "seed", "in": "query", "required": false, "description": "A booking or planning key; the spread strategy ranks bins by it, so a replay proposes the same bin.", "schema": { "description": "A booking or planning key; the spread strategy ranks bins by it, so a replay proposes the same bin.", "type": "string", "maxLength": 80 } }, { "name": "excludeBinIds", "in": "query", "required": false, "description": "Bins already tried and refused; never suggested again. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Bins already tried and refused; never suggested again.", "maxItems": 10, "type": "array", "items": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/replenishment": { "get": { "operationId": "replenishment_suggestions", "summary": "replenishment_suggestions", "description": "Every pick-face below its min level (WHT-016), bounded + cap-disclosed. For each SKU with a per-SKU record pinning a pick-face (homeLocationId) and a minQty, reports the pick-face available, the top-up target toward max, the best bulk source and its available, the move quantity (capped by source + pick-face capacity) and any live replenish task. Empty when nothing is below min.\n\n**Operation id:** `replenishment_suggestions` — the same operation is `app.replenishment.suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/replenishment_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "replenishment" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/replenishment/materialize": { "post": { "operationId": "replenishment_materialize", "summary": "replenishment_materialize", "description": "Turn below-min pick-faces into `replenish` move tasks (WHT-016), optionally restricted to a set of variants. Deduped: a pick-face that already has a live replenish task, or nothing to move / no source, is skipped. Returns the created task ids and each skipped pick-face with its reason.\n\n**Operation id:** `replenishment_materialize` — the same operation is `app.replenishment.materialize({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/replenishment_materialize`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "replenishment" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantIds": { "description": "Restrict to these variants (looked up by id, at most 200).", "maxItems": 200, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests": { "get": { "operationId": "return_requests_list", "summary": "return_requests_list", "description": "List customer-initiated return requests (RMAs, OMS-075), in the chosen order (`sort`; newest first by default), one page, with the order, resolution (refund/store_credit/exchange), line/unit counts and status. Filter by one or more statuses (requested, approved, denied, received, refunded, cancelled). `toRefund` lists what waits for money instead: received requests plus approved requests whose order already has a completed return receipt; each row carries `payout`, the newest settlement status. These are created on the store's returns page; this is the admin review queue.\n\n**Operation id:** `return_requests_list` — the same operation is `app.return.requests_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "requested", "approved", "denied", "received", "refunded", "cancelled" ] } } }, { "name": "toRefund", "in": "query", "required": false, "description": "What waits for money instead of a status: received, or approved with a completed receipt. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "What waits for money instead of a status: received, or approved with a completed receipt.", "type": "boolean" } }, { "name": "labelState", "in": "query", "required": false, "description": "Any of these return-label states (none, creating, sent, in_transit, delivered, failed); absent = any. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these return-label states (none, creating, sent, in_transit, delivered, failed); absent = any.", "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "none", "creating", "sent", "in_transit", "delivered", "failed" ] } } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`submitted:desc` (newest first, the default) or `submitted:asc` (longest waiting first).", "schema": { "description": "`submitted:desc` (newest first, the default) or `submitted:asc` (longest waiting first).", "type": "string", "enum": [ "submitted:desc", "submitted:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/approve": { "post": { "operationId": "return_requests_approve", "summary": "return_requests_approve", "description": "Approve a requested RMA. Approval authorizes the payout and settles it against what the dock actually received: if a return receipt for the order has already been completed, the refund / store credit / exchange release is enqueued by THIS call (the response carries the settled units and amount, and the RMA moves straight to received); otherwise it is enqueued when the goods are scanned in. Either way the amount covers only the units that came back in a sellable grade, priced at what the customer paid. received is not terminal: the outbox settle moves the RMA to refunded when the payout lands, and a payout that cannot be enqueued (all units damaged, exchange without a target) leaves the RMA received with a recorded resolution error — close it with return_requests_resolve.\n\n**Operation id:** `return_requests_approve` — the same operation is `app.return.requests_approve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_approve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string" } }, "required": [ "returnRequestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/cancel": { "post": { "operationId": "return_requests_cancel", "summary": "return_requests_cancel", "description": "Cancel a still-open RMA (requested or approved), withdrawing it before resolution.\n\n**Operation id:** `return_requests_cancel` — the same operation is `app.return.requests_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "returnRequestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/create-label": { "post": { "operationId": "return_requests_create_label", "summary": "return_requests_create_label", "description": "Create the return label of an APPROVED RMA with one carrier account (see return_requests_label_options). The label is made in the background: the answer is the attempt's id with status creating, and return_requests_get answers the label once it is issued (with its tracking number and documents) or failed (with the carrier's or the claim's refusal, e.g. return_request_closed). A carrier that charges the label when it is created needs `maxCost`, the most it may cost in the account's currency (refused max_cost_required without it). Refused: illegal_transition (not approved), return_label_exists (the RMA has a live label), return_label_unavailable with its reason, unknown_service, unknown_delivery. Pass a `requestKey` to make a retry safe.\n\n**Operation id:** `return_requests_create_label` — the same operation is `app.return.requests_create_label({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_create_label`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "description": "document id of the RMA.", "format": "floormode-id" }, "carrierAccountId": { "type": "string", "description": "document id of the parcel carrier account.", "format": "floormode-id" }, "serviceCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ], "description": "the return service (return_requests_label_options); null = the account's own." }, "weightGrams": { "description": "the parcel's weight in grams; the products' weights (else 500 g a unit) when omitted.", "type": "number", "exclusiveMinimum": 0, "maximum": 70000 }, "delivery": { "type": "string", "enum": [ "pdf", "qr", "both", "carrier_email" ], "description": "how the label reaches the customer." }, "maxCost": { "description": "the most the label may cost; required where the carrier charges when it is created.", "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount", "currency" ] }, "requestKey": { "description": "Caller-minted idempotency key (e.g. a UUID), one per logical submit.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "returnRequestId", "carrierAccountId", "serviceCode", "delivery" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/deny": { "post": { "operationId": "return_requests_deny", "summary": "return_requests_deny", "description": "Deny a requested RMA with an optional reason. A denied RMA never pays out.\n\n**Operation id:** `return_requests_deny` — the same operation is `app.return.requests_deny({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_deny`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string" } }, "required": [ "returnRequestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/get": { "get": { "operationId": "return_requests_get", "summary": "return_requests_get", "description": "Get one customer return request (RMA) with its lines, chosen resolution, estimated refund, prepaid-label state and the linked WMS receipt (refund-on-scan).\n\n**Operation id:** `return_requests_get` — the same operation is `app.return.requests_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "query", "parameters": [ { "name": "returnRequestId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/label-options": { "get": { "operationId": "return_requests_label_options", "summary": "return_requests_label_options", "description": "What a return label for one RMA can be made with: per active parcel carrier account (max 100) whether it can make this return's label now (`enabled`) and why not (`disabledReason`: no_return_carrier, no_return_address, carrier_cannot_return, awaiting_certification, awaiting_approval, cross_border_without_customs, customs_incomplete), its return services, the deliveries it offers this customer (pdf, qr, both, carrier_email), when it bills (`on_use`: free until posted; `at_creation`: charged when created) and the address the parcel goes to; the default the return label settings name; the parcel's weight and its source; and the customs declaration the label would carry. The same decision return_requests_create_label makes.\n\n**Operation id:** `return_requests_label_options` — the same operation is `app.return.requests_label_options({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_label_options`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "query", "parameters": [ { "name": "returnRequestId", "in": "query", "required": true, "description": "document id of the RMA.", "schema": { "type": "string", "description": "document id of the RMA.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/refresh-label-tracking": { "post": { "operationId": "return_requests_refresh_label_tracking", "summary": "return_requests_refresh_label_tracking", "description": "Ask the carrier for a return label's latest tracking: queued in the background, at most once a minute (a request still open is answered, not repeated). The label then moves to in transit, delivered or exception as the carrier's newest checkpoint says (see return_requests_get). Refused: a label that is not issued, in transit or in exception (`illegal_transition`), one with no carrier reference (`return_label_not_trackable`), a disconnected carrier account.\n\n**Operation id:** `return_requests_refresh_label_tracking` — the same operation is `app.return.requests_refresh_label_tracking({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_refresh_label_tracking`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "description": "A returnRequests id, e.g. \"returnRequests_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "returnLabelId": { "type": "string", "description": "A returnLabels id, e.g. \"returnLabels_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "returnRequestId", "returnLabelId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/resolve": { "post": { "operationId": "return_requests_resolve", "summary": "return_requests_resolve", "description": "Manually resolve a received RMA: moves it to its terminal refunded state after the merchant compensated the customer outside the automatic payout (or decided a fully-damaged return pays nothing). This is the exit for an RMA stuck at received — every unit graded damaged, an exchange with no replacement variant, or a refund/credit the outbox gave up on. Refused (`conflict`) while a payout is still being delivered.\n\n**Operation id:** `return_requests_resolve` — the same operation is `app.return.requests_resolve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_resolve`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string" } }, "required": [ "returnRequestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/settle": { "post": { "operationId": "return_requests_settle", "summary": "return_requests_settle", "description": "Settle an approved RMA against the goods the dock has already booked: the same payout an approval or a receipt completion enqueues (refund / store credit / exchange release for the units that came back in a sellable grade), for an RMA whose receipt was completed 'booked here only'. Answers `applied` (payout enqueued, RMA received) or `nothing_received` (no completed receipt of the order carries its goods — recorded on the RMA, nothing written). Refused (`conflict`) unless the RMA is approved.\n\n**Operation id:** `return_requests_settle` — the same operation is `app.return.requests_settle({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_settle`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "returnRequestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/return-requests/void-label": { "post": { "operationId": "return_requests_void_label", "summary": "return_requests_void_label", "description": "Take back an RMA's issued return label. A label billed only when posted whose carrier needs no void (DHL) is set `voided` (`superseded`) at once and a new one can be created; an unused one costs nothing (answer `status: voided`). A label only the carrier can take back (EasyPost, Sendcloud) is cancelled at the carrier in the background (answer `status: void_queued` with its `outboxId`): return_requests_get then shows the label voided (`carrier_void`, or `carrier_void_requested` when the carrier still confirms it) or, on the issued label, the carrier's refusal (`return_label_void_refused`) or an unanswered cancellation (`return_label_void_unresolved`: check the carrier account). Refused: a label no carrier takes back (`return_label_not_voidable`), the label of an RMA that is received, refunded, denied or cancelled (`return_request_closed`), an earlier cancellation still unanswered (`effect_in_flight`).\n\n**Operation id:** `return_requests_void_label` — the same operation is `app.return.requests_void_label({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/return_requests_void_label`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "return-requests" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnRequestId": { "type": "string", "description": "document id of the RMA.", "format": "floormode-id" }, "returnLabelId": { "type": "string", "description": "document id of the return label.", "format": "floormode-id" } }, "required": [ "returnRequestId", "returnLabelId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns": { "get": { "operationId": "returns_list", "summary": "returns_list", "description": "List mirrored Shopify returns, in the chosen order (`sort`; newest first by default), one page, with the order, the reverse-fulfillment-order count, the units expected back and the status of our return receipt. Filter by Shopify return status (REQUESTED, OPEN, CLOSED, DECLINED, CANCELED) or hide returns we already finished receiving.\n\n**Operation id:** `returns_list` — the same operation is `app.returns.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of REQUESTED, OPEN, CLOSED, DECLINED, CANCELED; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of REQUESTED, OPEN, CLOSED, DECLINED, CANCELED; absent = every status.", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "REQUESTED", "OPEN", "CLOSED", "DECLINED", "CANCELED" ] } } }, { "name": "openReceiptsOnly", "in": "query", "required": false, "description": "Only returns without a completed receipt of ours. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only returns without a completed receipt of ours.", "type": "boolean" } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (most recently recorded in Floormode first, the default) or `created:asc` (first recorded first).", "schema": { "description": "`created:desc` (most recently recorded in Floormode first, the default) or `created:asc` (first recorded first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/approve-request": { "post": { "operationId": "returns_approve_request", "summary": "returns_approve_request", "description": "Approve a return the customer requested in Shopify (OMS-1 G-15). Only a return in the Requested state, one decision per return at a time (action_in_flight). Shopify's return status is the proof: a return already approved settles as confirmed without asking again. The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `returns_approve_request` — the same operation is `app.returns.approve_request({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_approve_request`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "shopifyReturnId": { "type": "string", "minLength": 1, "description": "Numeric Shopify return id of a return the customer requested.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "notifyCustomer": { "type": "boolean", "description": "Tell the customer about the decision by email." } }, "required": [ "shopifyOrderId", "shopifyReturnId", "requestKey", "notifyCustomer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/create": { "post": { "operationId": "returns_create", "summary": "returns_create", "description": "Create a return in Shopify for shipped items of an order (OMS-1 G-15), with a return reason per line. Admitted only while no cancellation or item edit is in flight; the units are checked against what each line can still return, and while earlier returns are still being confirmed the answer is ok false with reason order_checking. Shopify's returnable items are read again before the return is created: when they no longer cover the request nothing is created and the request settles as not applied. The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `returns_create` — the same operation is `app.returns.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "shopifyLineItemId": { "type": "string", "minLength": 1, "description": "Numeric Shopify line item id, as listed in the order's lineItems.", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Shipped units of the line to return." }, "reason": { "type": "string", "enum": [ "damaged", "defective", "wrong_item", "not_as_described", "too_small", "too_large", "changed_mind", "arrived_late", "other" ], "description": "Why the customer returns it; sent to Shopify as the return reason." } }, "required": [ "shopifyLineItemId", "quantity", "reason" ] }, "description": "The shipped items the customer sends back." }, "notifyCustomer": { "type": "boolean", "description": "Send Shopify's return email to the customer." } }, "required": [ "shopifyOrderId", "requestKey", "lines", "notifyCustomer" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/decline-request": { "post": { "operationId": "returns_decline_request", "summary": "returns_decline_request", "description": "Decline a return the customer requested in Shopify (OMS-1 G-15) with Shopify's decline reason and an optional note to the customer. Only a return in the Requested state, one decision per return at a time (action_in_flight). The same requestKey with the same arguments replays the first answer.\n\n**Operation id:** `returns_decline_request` — the same operation is `app.returns.decline_request({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_decline_request`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyOrderId": { "type": "string", "minLength": 1, "description": "Numeric Shopify order id as a string.", "format": "floormode-id" }, "shopifyReturnId": { "type": "string", "minLength": 1, "description": "Numeric Shopify return id of a return the customer requested.", "format": "floormode-id" }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "notifyCustomer": { "type": "boolean", "description": "Tell the customer about the decision by email." }, "reason": { "type": "string", "enum": [ "final_sale", "return_period_ended", "other" ], "description": "Why the request is declined: Shopify's ReturnDeclineReason, lower-cased." }, "note": { "description": "A note to the customer about the decline.", "type": "string", "maxLength": 500 } }, "required": [ "shopifyOrderId", "shopifyReturnId", "requestKey", "notifyCustomer", "reason" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/get": { "get": { "operationId": "returns_get", "summary": "returns_get", "description": "Get one mirrored return with its reverse fulfillment orders (line items incl. dispositions and each line's product and variant title), reverse deliveries (tracking) and our return receipts.\n\n**Operation id:** `returns_get` — the same operation is `app.returns.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "returnId", "in": "query", "required": false, "description": "document id of the return.", "schema": { "description": "document id of the return.", "type": "string", "format": "floormode-id" } }, { "name": "shopifyReturnId", "in": "query", "required": false, "description": "Numeric Shopify return id.", "schema": { "description": "Numeric Shopify return id.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/label-settings": { "get": { "operationId": "returns_label_settings_get", "summary": "returns_label_settings_get", "description": "The return label settings and what they resolve to: the warehouse returns go to (null = the only active one), the carrier account (null = the first that can make return labels) and its return service, whether the customer portal makes labels itself (`portalAutoLabel`) and prefers a QR code (`preferQr`), the `revision`, the address the carrier sends returns to (a DHL account's returns receiver), and what makes a stored choice unusable.\n\n**Operation id:** `returns_label_settings_get` — the same operation is `app.returns.label_settings_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_label_settings_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "returns_label_settings_set", "summary": "returns_label_settings_set", "description": "Save the return label settings, fenced by `expectedRevision` (revision_mismatch when they changed meanwhile). Refused: carrier_account_unusable, unknown_service, return_address_incomplete. Answers the warning return_address_differs when a DHL account's returns receiver is not the chosen warehouse: DHL sends the parcels there.\n\n**Operation id:** `returns_label_settings_set` — the same operation is `app.returns.label_settings_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_label_settings_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnWarehouseId": { "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "carrierAccountId": { "anyOf": [ { "type": "string", "description": "A carrierAccounts id, e.g. \"carrierAccounts_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "serviceCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "portalAutoLabel": { "type": "boolean" }, "preferQr": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "the revision the settings were read at; refused revision_mismatch when it moved." } }, "required": [ "returnWarehouseId", "carrierAccountId", "serviceCode", "portalAutoLabel", "preferQr", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/policy": { "get": { "operationId": "returns_policy_get", "summary": "returns_policy_get", "description": "Get the returns policy (OMS-075): the return window in days after fulfillment and the SKUs / order tags that are final sale, whether the defaults are still in force (`isDefault`), and the address of the returns page in this store (`returnsUrl`, share it with customers; null while the store's address is unknown or its customer links lead to the carrier).\n\n**Operation id:** `returns_policy_get` — the same operation is `app.returns.policy_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_policy_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "returns_policy_set", "summary": "returns_policy_set", "description": "Replace the returns policy: `returnWindowDays` (between one day and one year after fulfillment), `finalSaleSkus` (never returnable, case-insensitive) and `finalSaleTags` (an order carrying one is final sale). The whole policy is written; the store's returns apply it on the next look.\n\n**Operation id:** `returns_policy_set` — the same operation is `app.returns.policy_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_policy_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnWindowDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "finalSaleSkus": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "finalSaleTags": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "returnWindowDays", "finalSaleSkus", "finalSaleTags" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts": { "get": { "operationId": "returns_receiving_list", "summary": "returns_receiving_list", "description": "List return receipts, in the chosen order (`sort`; newest first by default), one page, with units per disposition. Filter by status (open, received) or by the return they belong to.\n\n**Operation id:** `returns_receiving_list` — the same operation is `app.returns.receiving_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of open, received, cancelled; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of open, received, cancelled; absent = every status.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "open", "received", "cancelled" ] } } }, { "name": "returnId", "in": "query", "required": false, "description": "Receipts of this return only.", "schema": { "description": "Receipts of this return only.", "type": "string", "format": "floormode-id" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "returns_receiving_create", "summary": "returns_receiving_create", "description": "Open a return receipt (`#RET-…`). Link it to a mirrored return by returnId or shopifyReturnId; without either it is a blind return (goods without a Shopify return), which may still be attributed to an order via shopifyOrderId.\n\n**Operation id:** `returns_receiving_create` — the same operation is `app.returns.receiving_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "returnId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "shopifyReturnId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "shopifyOrderId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/cancel": { "post": { "operationId": "returns_receiving_cancel", "summary": "returns_receiving_cancel", "description": "Cancel an OPEN return receipt that has booked nothing — the exit for a receipt opened against the wrong return or by mistake. Terminal (`open → cancelled`); no stock moves and nothing is reported to Shopify. Refused with `conflict` (`code: receipt_has_lines`) once a line is booked, because every booked line already moved stock: complete the receipt instead. Idempotent on an already-cancelled receipt.\n\n**Operation id:** `returns_receiving_cancel` — the same operation is `app.returns.receiving_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnReceiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reason": { "description": "Why it was cancelled (timeline only).", "type": "string" } }, "required": [ "returnReceiptId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/complete": { "post": { "operationId": "returns_receiving_complete", "summary": "returns_receiving_complete", "description": "Close a return receipt. For every reverse fulfillment order it touched, one `rfo_dispose` job is queued: restock → RESTOCKED, quarantine → PROCESSING_REQUIRED, scrap → NOT_RESTOCKED — the graded condition is kept on the line and does not change the Shopify disposition. The tenant object only records the intent; the Worker executes `reverseFulfillmentOrderDispose`. Refund-on-scan is a declared choice: `payOutApprovedRequests` (default true) resolves the approved return requests of the receipt's order — refund / store credit / exchange ride the outbox — and `false` closes the receipt while leaving them approved (`unresolvedRequests`).\n\n**Operation id:** `returns_receiving_complete` — the same operation is `app.returns.receiving_complete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_complete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnReceiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "payOutApprovedRequests": { "description": "Resolve the order's approved RMAs on completion (default true).", "type": "boolean" } }, "required": [ "returnReceiptId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/get": { "get": { "operationId": "returns_receiving_get", "summary": "returns_receiving_get", "description": "Get one return receipt with its graded lines (condition, disposition, bin and the Shopify disposition type each line will report). `unmatchedLines` counts the graded lines of a return-linked receipt that matched NO reverse fulfillment order line — their disposition is never reported to Shopify (each is also a `return_line_unmatched` timeline event); always 0 for a blind receipt.\n\n**Operation id:** `returns_receiving_get` — the same operation is `app.returns.receiving_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "returnReceiptId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/inspection": { "get": { "operationId": "returns_inspection_context", "summary": "returns_inspection_context", "description": "Read receipt-linked quarantine inspection quantities, original grading and stock-proof blockers.\n\n**Operation id:** `returns_inspection_context` — the same operation is `app.returns.inspection_context({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_inspection_context`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "returnReceiptId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/inspection/history": { "get": { "operationId": "returns_inspection_history", "summary": "returns_inspection_history", "description": "Read immutable inspection releases for one return receipt line, newest first. Each row preserves actor, reason, quantity, time and exact movement/bin/lot identities. Pass the returned cursor to read older decisions.\n\n**Operation id:** `returns_inspection_history` — the same operation is `app.returns.inspection_history({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_inspection_history`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "query", "parameters": [ { "name": "returnReceiptLineId", "in": "query", "required": true, "description": "A returnReceiptLines id, e.g. \"returnReceiptLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A returnReceiptLines id, e.g. \"returnReceiptLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/inspection/release": { "post": { "operationId": "returns_inspection_release", "summary": "returns_inspection_release", "description": "Record an explicit physical inspection and move the exact returned quantity and lot into a sellable bin. Preserves original grading and Shopify disposition; never retries disposal or refunds.\n\n**Operation id:** `returns_inspection_release` — the same operation is `app.returns.inspection_release({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_inspection_release`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnReceiptLineId": { "type": "string", "description": "A returnReceiptLines id, e.g. \"returnReceiptLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "qty": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "toBinId": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "physicallyInspected": { "type": "boolean", "const": true }, "expectedReleasedQty": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "returnReceiptLineId", "qty", "toBinId", "reason", "physicallyInspected", "expectedReleasedQty", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/returns/receipts/record-line": { "post": { "operationId": "returns_receiving_record_line", "summary": "returns_receiving_record_line", "description": "Receive one returned item. The disposition drives the ledger: restock → `return` movement into a sellable bin (Shopify availability follows), quarantine → `return` movement into the warehouse's QUAR-01 bin (created on first use, not sellable), scrap → no stock movement at all. Damaged goods cannot be restocked. The line is matched to a reverse-fulfillment-order line automatically (or via rfoLineItemId) so `returns_receiving_complete` can dispose it on Shopify; a booking that brings more than the return still expects links the expected units and books the rest on a line of its own (`surplusQty`), which Shopify is never told about. A LOCAL item (VMAT-/ASM-/CSTM-) is a resolvable scan code like any other, so the same ownership gate applies: restocking one mirrors the new levels to its owning peer, and is refused with a coded `details.localRefusal` when the item is frozen history, still unplaced, a catalog placeholder, or archived by its owner. For an item that tracks lots, restocking or quarantining without a lot into a bin that already holds lot-tracked units of it is refused with `details.code: \"lot_required\"`. Any item may name a lot it already has; only an item that tracks lots may bring a new one (`details.code: \"lot_not_tracked\"`).\n\n**Operation id:** `returns_receiving_record_line` — the same operation is `app.returns.receiving_record_line({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/returns_receiving_record_line`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "returns" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnReceiptId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedCode": { "description": "Item barcode or sku.", "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "condition": { "description": "Defaults to sellable.", "type": "string", "enum": [ "sellable", "damaged" ] }, "disposition": { "type": "string", "enum": [ "restock", "quarantine", "scrap" ] }, "toBinId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "toBinCode": { "type": "string" }, "reasonCode": { "description": "A known adjustment reason (damaged, lost, …); an unknown code is refused.", "type": "string" }, "rfoLineItemId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "lotNumber": { "description": "Lot of the returned goods, only for a disposition that enters stock: a lot the item already has, or a new one for an item that tracks lots.", "type": "string" }, "expiryDate": { "description": "ISO calendar day the lot expires on; only together with a lot number.", "type": "string" }, "serials": { "description": "One serial per returned unit, for an item that tracks serials: each must have shipped on this return's order (serial_not_from_order otherwise). A restock puts an item that records its serials at receiving back in stock; a scrap scraps the units.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "required": [ "returnReceiptId", "qty", "disposition" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/roles": { "get": { "operationId": "roles_list", "summary": "roles_list", "description": "List the roles (max 200): the built-in Admin, Manager and Floor roles and the custom roles, each with the permissions it allows now. A custom role edit WorkOS has not confirmed yet is marked pending and counts only where it narrows. Archived roles are left out.\n\n**Operation id:** `roles_list` — the same operation is `app.roles.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/roles_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "roles" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "roles_save", "summary": "roles_save", "description": "Create (no roleId) or edit a custom role: name, description, permissions. Needs team.roles and the caller's own P&H account; only permissions the caller holds; the built-in Admin, Manager and Floor roles are read-only (duplicate them). The role is written to the P&H account; until it confirms, the role allows only what both the old and the new permissions allow.\n\n**Operation id:** `roles_save` — the same operation is `app.roles.save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/roles_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "roles" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 48 }, "description": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "permissions": { "maxItems": 40, "type": "array", "items": { "type": "string", "enum": [ "orders.view", "orders.manage", "orders.cancel_refund", "fulfillment.view", "fulfillment.plan", "fulfillment.assign", "shipping.labels", "inventory.view", "inventory.adjust", "inventory.counts", "inventory.transfers", "receiving.manage", "catalog.manage", "returns.view", "returns.manage", "reports.view", "warehouse.setup", "automation.manage", "settings.manage", "integrations.manage", "privacy.manage", "billing.manage", "api.use", "stores.manage", "team.view", "team.people", "team.roles", "team.devices", "labour.today", "labour.shifts", "labour.timesheets", "labour.productivity", "floor.use", "floor.pick", "floor.pack", "floor.receive", "floor.count", "floor.move", "floor.approve", "floor.wallboard" ] } } }, "required": [ "name", "permissions" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/roles/archive": { "post": { "operationId": "roles_archive", "summary": "roles_archive", "description": "Archive a custom role nobody holds: it is deleted in the P&H account and leaves the role list once that confirms. Refused while a person, a P&H membership or the default staff role uses it.\n\n**Operation id:** `roles_archive` — the same operation is `app.roles.archive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/roles_archive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "roles" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "roleId", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/roles/duplicate": { "post": { "operationId": "roles_duplicate", "summary": "roles_duplicate", "description": "Copy a built-in or custom role into a new custom role (name defaults to the source's name with \"copy\"). Only permissions the caller holds.\n\n**Operation id:** `roles_duplicate` — the same operation is `app.roles.duplicate({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/roles_duplicate`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "roles" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "description": "A roles id, e.g. \"roles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1, "maxLength": 48 } }, "required": [ "roleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/dropship-pos": { "get": { "operationId": "dropship_pos_list", "summary": "dropship_pos_list", "description": "List the newest dropship purchase orders (max 200): the vendor, order, lines, status (draft → sent → tracked → received/cancelled) and any captured vendor tracking.\n\n**Operation id:** `dropship_pos_list` — the same operation is `app.dropship.pos_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_pos_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "dropship_po_create", "summary": "dropship_po_create", "description": "Manually route an order to a dropship vendor: create the PO + enqueue the vendor email (dropship_po outbox). Idempotent per (order, vendor).\n\n**Operation id:** `dropship_po_create` — the same operation is `app.dropship.po_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_po_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "vendorId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "orderId", "vendorId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/dropship-pos/tracking": { "post": { "operationId": "dropship_po_record_tracking", "summary": "dropship_po_record_tracking", "description": "Capture the carrier + tracking a dropship vendor reported (moves the PO to `tracked`). Pass null to clear.\n\n**Operation id:** `dropship_po_record_tracking` — the same operation is `app.dropship.po_record_tracking({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_po_record_tracking`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dropshipPoId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "carrier": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "tracking": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "dropshipPoId", "carrier", "tracking" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/preview": { "get": { "operationId": "dom_routing_preview", "summary": "dom_routing_preview", "description": "Preview where an order would ship from with the current rules + defaults, WITHOUT any side effect: `decisions`, one per open fulfillment order (`fulfillment` = its id and its 'Fulfillment #N' on the order page), or one with `fulfillment` null when the decision is the whole order's (a rule, a vendor, a refusal, or no fulfillment order yet). Each carries the decision kind (warehouse / dropship / unchanged / unsupported), the resolved warehouse or vendor, and the reason (rule / nearest / most_available / none_can_fill / only / none / kept / work_started / order_too_large). Without a matching rule the default is stock-aware: among the active warehouses whose pickable stock covers EVERY ordered item, the nearest to the delivery address (`nearest`) or, with no distance to measure, the best stocked (`most_available`); when none covers every item, the one holding the most of the ordered units (`none_can_fill`). Stock is what allocation could reserve (pickable, sellable, unflagged bins), measured against what the order still owes (its open fulfillment orders); it counts the order's own reservations and picked units, and counts a bundle as held where its parts can build it. The default is sticky per fulfillment order: one already reserved in a warehouse that can still fill the order stays there (`kept`), and once picking started there it stays even when it no longer can (`work_started`); a matching rule still moves it. `unchanged` and `unsupported` (reason `order_too_large`) are 'no decision'.\n\n**Operation id:** `dom_routing_preview` — the same operation is `app.dom.routing_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_routing_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "query", "parameters": [ { "name": "orderId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/rules": { "get": { "operationId": "dom_rules_list", "summary": "dom_rules_list", "description": "List the distributed order routing rules in cascade (position) order. Each is an ordered predicate→target row (first enabled match wins): the predicate tests the order (destinationCountry/Region, sku, weightRange, valueRange) and the target sources it (warehouse / ship-from-store / dropship vendor). No rules ⇒ today's allocation (no regression). Each row carries `resolvedTarget` {name, state}: the target's name and whether the router can honour it — active, inactive (deactivated), deleted (a soft-deleted vendor) or missing — so a rule that routes nothing is visible as such.\n\n**Operation id:** `dom_rules_list` — the same operation is `app.dom.rules_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_rules_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "dom_rules_create", "summary": "dom_rules_create", "description": "Create a routing rule (appended last in the cascade). The target references must belong to the tenant (warehouse/store → a warehouse; dropship → a vendor); an empty predicate is a catch-all default rule.\n\n**Operation id:** `dom_rules_create` — the same operation is `app.dom.rules_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_rules_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "predicate": { "type": "object", "properties": { "destinationCountry": { "description": "Delivery country match (case-insensitive).", "type": "string" }, "destinationRegion": { "description": "Delivery province/state (case-insensitive).", "type": "string" }, "sku": { "description": "Matches when ANY order line carries this SKU.", "type": "string" }, "weightRange": { "description": "Total shippable weight band in grams.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "valueRange": { "description": "Order total band in the order currency's major units.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } } }, "description": "Order test; every declared dimension must hold (AND). Empty ⇒ matches every order." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "warehouse", "dropship", "store" ] }, "warehouseId": { "description": "document id of the source warehouse/store.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "dropshipVendorId": { "description": "document id of the dropship vendor.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "required": [ "kind" ], "description": "Where a matched order is sourced (warehouse / ship-from-store / dropship vendor)." }, "enabled": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "name", "predicate", "target" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/rules/delete": { "post": { "operationId": "dom_rules_delete", "summary": "dom_rules_delete", "description": "Soft-delete a routing rule.\n\n**Operation id:** `dom_rules_delete` — the same operation is `app.dom.rules_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_rules_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/rules/reorder": { "post": { "operationId": "dom_rules_reorder", "summary": "dom_rules_reorder", "description": "Move a routing rule one slot up or down the cascade by swapping positions (lower position is evaluated first).\n\n**Operation id:** `dom_rules_reorder` — the same operation is `app.dom.rules_reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_rules_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "direction": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "ruleId", "direction" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/rules/update": { "post": { "operationId": "dom_rules_update", "summary": "dom_rules_update", "description": "Update a routing rule: name, enabled, predicate or target. Only passed fields change.\n\n**Operation id:** `dom_rules_update` — the same operation is `app.dom.rules_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dom_rules_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean" }, "predicate": { "type": "object", "properties": { "destinationCountry": { "description": "Delivery country match (case-insensitive).", "type": "string" }, "destinationRegion": { "description": "Delivery province/state (case-insensitive).", "type": "string" }, "sku": { "description": "Matches when ANY order line carries this SKU.", "type": "string" }, "weightRange": { "description": "Total shippable weight band in grams.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "valueRange": { "description": "Order total band in the order currency's major units.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } } }, "description": "Order test; every declared dimension must hold (AND). Empty ⇒ matches every order." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "warehouse", "dropship", "store" ] }, "warehouseId": { "description": "document id of the source warehouse/store.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "dropshipVendorId": { "description": "document id of the dropship vendor.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "required": [ "kind" ], "description": "Where a matched order is sourced (warehouse / ship-from-store / dropship vendor)." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/vendors": { "get": { "operationId": "dropship_vendors_list", "summary": "dropship_vendors_list", "description": "List the active dropship vendors (name + email a dropship PO is sent to).\n\n**Operation id:** `dropship_vendors_list` — the same operation is `app.dropship.vendors_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_vendors_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "dropship_vendors_create", "summary": "dropship_vendors_create", "description": "Create a dropship vendor. email is where the dropship PO is emailed (null or a blank string means none); a vendor with no email settles its POs as a non-retryable 'no recipient'. A malformed address is refused with invalid_input.\n\n**Operation id:** `dropship_vendors_create` — the same operation is `app.dropship.vendors_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_vendors_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 0 }, { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } ] }, { "type": "null" } ] }, "active": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "name", "email" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/vendors/delete": { "post": { "operationId": "dropship_vendors_delete", "summary": "dropship_vendors_delete", "description": "Soft-delete a dropship vendor.\n\n**Operation id:** `dropship_vendors_delete` — the same operation is `app.dropship.vendors_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_vendors_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "vendorId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/routing/vendors/update": { "post": { "operationId": "dropship_vendors_update", "summary": "dropship_vendors_update", "description": "Update a dropship vendor: name, email (null or a blank string clears; a malformed address is refused) or active. Only passed fields change.\n\n**Operation id:** `dropship_vendors_update` — the same operation is `app.dropship.vendors_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/dropship_vendors_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "routing" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 0 }, { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } ] }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "vendorId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules": { "get": { "operationId": "rules_list", "summary": "rules_list", "description": "List the tenant's automation rules in cascade (position) order. Each rule has a trigger (order_created, order_paid, order_routing_complete, order_risk_changed), conditions, matchAll (AND/OR) and actions (add_tag, hold, set_priority, route_to_warehouse, notify).\n\n**Operation id:** `rules_list` — the same operation is `app.rules.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "rules_create", "summary": "rules_create", "description": "Create an automation rule. It is added at the end of the cascade and enabled by default. Conditions test order facts (channel, tag, sku, total, destinationCountry, shippingOption, riskLevel, weight, lineCount, dangerousGoods); matchAll true = AND, false = ANY.\n\n**Operation id:** `rules_create` — the same operation is `app.rules.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `automation`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "trigger": { "type": "string", "enum": [ "order_created", "order_paid", "order_routing_complete", "order_risk_changed" ] }, "conditions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "channel", "tag", "sku", "total", "destinationCountry", "shippingOption", "riskLevel", "weight", "lineCount", "dangerousGoods" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "description": "`neq` and `in` take a comma-separated list. For `shippingOption` (the customer's checkout option), `eq` / `neq` / `in` take ids from checkout_options_list and `contains` matches the title; `gt` / `lt` are refused, and a rule with this condition is skipped while the order's option is unknown. For `dangerousGoods` (the classes the order's or the parcel's items are marked with; `none` when it holds none), `eq` / `neq` / `in` take class keys (lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated, none); `contains`, `gt` and `lt` are refused." } }, "matchAll": { "type": "boolean" }, "actions": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "add_tag" }, "params": { "type": "object", "properties": { "tag": { "type": "string" } }, "required": [ "tag" ], "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "hold" }, "params": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other" ] }, "note": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "set_priority" }, "params": { "type": "object", "properties": { "priority": { "type": "string" } }, "required": [ "priority" ], "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "route_to_warehouse" }, "params": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "warehouse": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notify" }, "params": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "required": [ "type", "params" ] } ], "description": "Discriminated on `type`; each type has its own params object: add_tag {tag}, hold {reason?, note?}, set_priority {priority}, route_to_warehouse {warehouseId?, warehouse?}, notify {severity?, message?} (message: 1..1000 characters, non-blank)." } }, "enabled": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "name", "trigger", "conditions", "matchAll", "actions" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules/delete": { "post": { "operationId": "rules_delete", "summary": "rules_delete", "description": "Soft-delete an automation rule; its run history is kept.\n\n**Operation id:** `rules_delete` — the same operation is `app.rules.delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `automation`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules/preview": { "get": { "operationId": "rules_preview", "summary": "rules_preview", "description": "Dry-run a rule against one mirrored order (by numeric Shopify order id): returns whether it would match and the would-be action labels, without applying anything. `factsComplete: false` names the fact the order cannot answer yet in `unknownFact` (`sku`: more SKUs than the facts carry; `shippingOption`: its checkout option is not known yet); the live rule skips such an order rather than guess.\n\n**Operation id:** `rules_preview` — the same operation is `app.rules.preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "query", "parameters": [ { "name": "ruleId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "sampleShopifyOrderId", "in": "query", "required": true, "description": "Numeric Shopify order id as a string.", "schema": { "type": "string", "description": "Numeric Shopify order id as a string.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules/reorder": { "post": { "operationId": "rules_reorder", "summary": "rules_reorder", "description": "Move a rule one slot up or down the cascade (rules run in position order, lowest first). Returns moved:false when it is already at the end in that direction.\n\n**Operation id:** `rules_reorder` — the same operation is `app.rules.reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `automation`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "direction": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "ruleId", "direction" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules/runs": { "get": { "operationId": "rule_runs_list", "summary": "rule_runs_list", "description": "List the run log of one automation rule, newest first (max 100). Each run records the order it fired on, the trigger and the actions applied — the audit behind the \"matched rule X\" timeline entries.\n\n**Operation id:** `rule_runs_list` — the same operation is `app.rule.runs_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rule_runs_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "query", "parameters": [ { "name": "ruleId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/rules/update": { "post": { "operationId": "rules_update", "summary": "rules_update", "description": "Update an automation rule. Any field may be changed independently — pass only what you want to change (e.g. enabled to toggle the rule on or off).\n\n**Operation id:** `rules_update` — the same operation is `app.rules.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/rules_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `elevate` (feature `automation`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "rules" ], "x-operation-kind": "mutation", "x-min-plan": "elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "document id of the rule.", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean" }, "trigger": { "type": "string", "enum": [ "order_created", "order_paid", "order_routing_complete", "order_risk_changed" ] }, "conditions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "channel", "tag", "sku", "total", "destinationCountry", "shippingOption", "riskLevel", "weight", "lineCount", "dangerousGoods" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "description": "`neq` and `in` take a comma-separated list. For `shippingOption` (the customer's checkout option), `eq` / `neq` / `in` take ids from checkout_options_list and `contains` matches the title; `gt` / `lt` are refused, and a rule with this condition is skipped while the order's option is unknown. For `dangerousGoods` (the classes the order's or the parcel's items are marked with; `none` when it holds none), `eq` / `neq` / `in` take class keys (lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated, none); `contains`, `gt` and `lt` are refused." } }, "matchAll": { "type": "boolean" }, "actions": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "add_tag" }, "params": { "type": "object", "properties": { "tag": { "type": "string" } }, "required": [ "tag" ], "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "hold" }, "params": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other" ] }, "note": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "set_priority" }, "params": { "type": "object", "properties": { "priority": { "type": "string" } }, "required": [ "priority" ], "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "route_to_warehouse" }, "params": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "warehouse": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notify" }, "params": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "required": [ "type", "params" ] } ], "description": "Discriminated on `type`; each type has its own params object: add_tag {tag}, hold {reason?, note?}, set_priority {priority}, route_to_warehouse {warehouseId?, warehouse?}, notify {severity?, message?} (message: 1..1000 characters, non-blank)." } } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/saved-views": { "get": { "operationId": "saved_views_list", "summary": "saved_views_list", "description": "The saved list views this caller may see — their own plus the ones shared with the whole shop — as summaries (no filters), optionally for one list. Read a view's filters, sort and columns with saved_views_get.\n\n**Operation id:** `saved_views_list` — the same operation is `app.saved.views_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "query", "parameters": [ { "name": "surface", "in": "query", "required": false, "description": "One list, or every list.", "schema": { "description": "One list, or every list.", "type": "string", "enum": [ "orders", "shipments", "receipts", "transfers", "stock", "packJobs", "batches", "returnRequests", "movements", "counts", "returns", "returnReceipts", "exceptions", "alerts", "bins", "pickQueue", "production", "floorTasks", "orderMerges", "releases", "checkoutOptions", "lots", "lotShips", "timeEntries", "serials" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "saved_views_save", "summary": "saved_views_save", "description": "Create or update a saved view: a name and the envelope { v, surface, filters, sort, columns } — the filters are validated against that list's query. Pass savedViewId to update, expectedRevision (its updatedAt) to refuse a view someone else moved, shared: true to make it the whole shop's.\n\n**Operation id:** `saved_views_save` — the same operation is `app.saved.views_save({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_save`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "savedViewId": { "description": "Update this view; omitted creates one.", "type": "string", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "oneOf": [ { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "orders" }, "filters": { "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "open", "unfulfilled", "partial", "fulfilled", "restocked", "cancelled" ] } }, "holdState": { "type": "string", "enum": [ "held", "unheld", "all" ] }, "allocationState": { "type": "string", "enum": [ "none", "allocated", "short", "released", "all" ] }, "holdReason": { "type": "string", "enum": [ "payment_pending", "fraud_risk", "address_issue", "awaiting_stock", "awaiting_production", "awaiting_supplier", "customer_request", "other", "all" ] }, "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "all" ] }, "tag": { "type": "string" }, "window": { "type": "string", "enum": [ "all", "today", "7d", "30d" ] }, "destinationCountry": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "deliveryMethod": { "default": [], "type": "array", "items": { "type": "string", "enum": [ "shipping", "pickup", "local_delivery", "other" ] } }, "packDay": { "default": [], "type": "array", "items": { "type": "string", "enum": [ "overdue", "today", "next", "later", "no_date", "unreadable" ] } }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] }, "shippingOption": { "default": null, "anyOf": [ { "type": "string", "description": "A checkoutOptions id, e.g. \"checkoutOptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] }, "stalled": { "default": false, "type": "boolean" } }, "required": [ "search", "status", "holdState", "allocationState", "holdReason", "riskLevel", "tag", "window", "destinationCountry" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "order", "store", "status", "blocked", "fulfillment", "destination", "shippingOption", "total", "age", "due", "deliveryDate" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "shipments" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "draft", "rated", "purchasing", "purchased", "in_transit", "delivered", "exception", "voided", "refund_pending" ] } }, "search": { "type": "string", "maxLength": 100 }, "fallbackOnly": { "default": false, "type": "boolean" }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] } }, "required": [ "status", "search" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "shipment", "store", "status", "carrier", "tracking", "cost", "printed", "created" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "receipts" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "expected", "receiving", "received", "cancelled" ] } }, "source": { "anyOf": [ { "type": "string", "enum": [ "manual", "warehouse_transfer", "logistified_po", "logistified_to", "assemblified_wo" ] }, { "type": "null" } ] }, "warehouseId": { "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string", "enum": [ "inspecting", "putting_away" ] }, { "type": "null" } ] } }, "required": [ "status", "source", "warehouseId" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc", "promised:asc", "promised:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "receipt", "status", "source", "supplier", "warehouse", "promised", "lines", "expected", "received", "discrepancies" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "transfers" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "draft", "ready", "in_progress", "completed", "cancelled" ] } }, "channelState": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "not_required", "pending", "confirmed", "refused", "ambiguous" ] } }, "warehouseId": { "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "direction": { "type": "string", "enum": [ "from", "to", "either" ] } }, "required": [ "status", "channelState", "warehouseId", "direction" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc", "updated:desc", "updated:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "transfer", "route", "status", "channel", "adapter", "planned", "staged", "dispatched", "inTransit", "received", "created", "updated" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "stock" }, "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 200 }, "source": { "anyOf": [ { "type": "string", "enum": [ "shopify", "assemblified_virtual_material", "assemblified_sub_assembly", "logistified_custom_item" ] }, { "type": "null" } ] }, "customs": { "default": null, "anyOf": [ { "type": "string", "enum": [ "complete", "missing_hs", "missing_origin" ] }, { "type": "null" } ] }, "tracking": { "default": null, "anyOf": [ { "type": "string", "enum": [ "none", "lot", "serial" ] }, { "type": "null" } ] }, "scanning": { "default": null, "anyOf": [ { "type": "string", "enum": [ "blocked", "no_scan" ] }, { "type": "null" } ] }, "dangerousGoods": { "default": [], "type": "array", "items": { "type": "string", "enum": [ "lithium_in_equipment", "lithium_with_equipment", "lithium_alone", "limited_quantity", "regulated" ] } } }, "required": [ "search", "source" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "id:asc", "item:asc", "item:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "item", "source", "hsCode", "tracking", "dangerousGoods", "warehouses", "onHand", "demand", "available", "shopifyOnHand", "unassigned", "incoming" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "packJobs" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "pending", "verifying", "verified", "fulfill_queued", "prepared", "fulfilled", "failed", "cancelled" ] } }, "warehouseId": { "anyOf": [ { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] } }, "required": [ "statuses", "warehouseId" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "job", "store", "order", "status", "scanned", "tracking", "updated" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "batches" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "open", "picking", "picked", "cancelled" ] } }, "source": { "anyOf": [ { "type": "string", "enum": [ "shopify_fo", "assemblified_wo" ] }, { "type": "null" } ] }, "profileId": { "default": null, "anyOf": [ { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } }, "required": [ "statuses", "source" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "batch", "status", "warehouse", "progress", "orders", "lines", "units" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "returnRequests" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "requested", "approved", "denied", "received", "refunded", "cancelled" ] } }, "toRefund": { "type": "boolean" }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] } }, "required": [ "status", "toRefund" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "submitted:desc", "submitted:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "request", "store", "items", "refund", "reason", "status", "label", "waiting" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "movements" }, "filters": { "type": "object", "properties": { "kinds": { "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "receipt", "putaway", "pick", "pack", "ship", "adjust", "count", "return", "move", "release", "import", "opening" ] } }, "reasonCode": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "window": { "type": "string", "enum": [ "all", "today", "7d", "30d" ] }, "variantId": { "anyOf": [ { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "binId": { "anyOf": [ { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } }, "required": [ "kinds", "reasonCode", "window", "variantId", "binId" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "at:desc", "at:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "when", "kind", "item", "bins", "quantity", "reason", "reference", "who" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "counts" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "open", "counting", "review", "approved", "cancelled" ] } } }, "required": [ "statuses" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "count", "status", "warehouse", "bins", "counted", "varianceLines", "varianceUnits" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "returns" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "REQUESTED", "OPEN", "CLOSED", "DECLINED", "CANCELED" ] } }, "openReceiptsOnly": { "type": "boolean" }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] } }, "required": [ "status", "openReceiptsOnly" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "return", "store", "status", "order", "expectedUnits", "receipts", "requested", "added" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "returnReceipts" }, "filters": { "type": "object", "properties": { "status": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "open", "received", "cancelled" ] } } }, "required": [ "status" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "receipt", "status", "warehouse", "restocked", "quarantined", "writtenOff", "opened" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "exceptions" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "open", "resolved" ] } }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "statuses", "reason" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "at:desc", "at:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "shipment", "reason", "note", "opened", "status", "tracking", "resolved" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "alerts" }, "filters": { "type": "object", "properties": { "severities": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "info", "warning", "critical" ] } }, "type": { "anyOf": [ { "type": "string", "enum": [ "automation_rule", "backorder", "backorder_restocked", "barcode_aliases_refused", "checkout_options_cap_reached", "count_variance", "external_fulfillment_unbooked", "fo_close_deferred", "handback_overdue", "integration_key_reuse", "inventory_writer_drift", "inventory_writer_drift_cleared", "inventory_writer_gap", "landed_cost_refused", "local_snapshot_skipped", "lot_blocked", "lot_expiry_tightened", "near_expiry", "order_action_attention", "order_edit_mirror_refresh_dead", "order_refresh_dead", "oversell_risk", "pack_ship_skipped", "payment_auth_window", "peer_capability_revoked", "peer_reachable", "peer_unreachable", "pick_lines_dropped", "pick_release_skipped", "po_push_confirmation_overflow", "receipt_price_deviation", "refund_failure", "refund_stock_unbooked", "reorder_suggested", "return_label_unprintable", "rule_matched_noop", "shipment_weight_estimated", "sibling_report_refused", "sla_breach", "source_lines_exceeded", "stock_release_clamped", "sync_failure", "token_refresh_refused", "token_refresh_unresolved", "transfer_source_effect_refused", "wave_auto_release_refused" ] }, { "type": "null" } ] }, "window": { "type": "string", "enum": [ "all", "today", "7d", "30d" ] }, "state": { "default": "open", "type": "string", "enum": [ "open", "all" ] } }, "required": [ "severities", "type", "window" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "at:desc", "at:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "when", "severity", "alert", "message", "about", "from", "delivery" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "bins" }, "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 40 }, "zoneId": { "anyOf": [ { "type": "string", "description": "A zones id, e.g. \"zones_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "binTypes": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "receiving", "qc", "quarantine", "bulk", "pick", "packing", "staging", "returns", "unassigned" ] } }, "level": { "type": "string", "enum": [ "bins", "all" ] }, "state": { "type": "string", "enum": [ "active", "archived", "all" ] }, "occupancy": { "anyOf": [ { "type": "string", "enum": [ "empty", "occupied" ] }, { "type": "null" } ] }, "sellable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "pickable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "flagged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "search", "zoneId", "binTypes", "level", "state", "occupancy", "sellable", "pickable", "flagged" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "code:asc", "code:desc", "route:asc", "route:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "bin", "zone", "type", "flags", "pickSequence", "contents", "barcode", "path", "limits" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "pickQueue" }, "filters": { "type": "object", "properties": { "singles": { "type": "boolean" }, "assignment": { "anyOf": [ { "type": "string", "enum": [ "mine", "unassigned" ] }, { "type": "null" } ] }, "lateOnly": { "type": "boolean" }, "profileId": { "default": null, "anyOf": [ { "type": "string", "description": "A pickProfiles id, e.g. \"pickProfiles_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "store": { "default": null, "anyOf": [ { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "null" } ] } }, "required": [ "singles", "assignment", "lateOnly" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "allocated:asc", "allocated:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "order", "store", "status", "destination", "units", "allocated", "age", "due", "assignee" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "production" }, "filters": { "type": "object", "properties": { "stages": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "announced", "picking", "staged", "in_production", "awaiting_putaway", "put_away", "cancelled" ] } } }, "required": [ "stages" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "due:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "workOrder", "stage", "due", "materials", "shortLines", "receipt", "batch", "age" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "floorTasks" }, "filters": { "type": "object", "properties": { "types": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } }, "statuses": { "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "pending", "claimed", "assigned", "inProgress", "done", "cancelled" ] } }, "assignment": { "anyOf": [ { "type": "string", "enum": [ "mine", "unassigned" ] }, { "type": "null" } ] } }, "required": [ "types", "statuses", "assignment" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:asc", "created:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "task", "status", "units", "age", "created", "assignee" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "orderMerges" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "open", "cancelled", "fulfilled" ] } } }, "required": [ "statuses" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "group", "status", "members", "created" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "releases" }, "filters": { "type": "object", "properties": { "statuses": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "planned", "released", "closed" ] } } }, "required": [ "statuses" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "created:desc", "created:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "name", "status", "orders", "units", "created" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "checkoutOptions" }, "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 100 }, "statuses": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "needs_review", "mapped", "rules", "no_label" ] } }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shopify_rate", "carrier_app", "pickup", "local_delivery", "other" ] } }, "seen": { "anyOf": [ { "type": "string", "enum": [ "7d", "30d", "stale" ] }, { "type": "null" } ] } }, "required": [ "search", "statuses", "sources", "seen" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "review:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "option", "shipWith", "orders", "lastSeen" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "lots" }, "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 64 }, "variantId": { "anyOf": [ { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] } }, "required": [ "search", "variantId" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "lot:asc", "lot:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "lot", "item", "expiry", "status", "onHand" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "lotShips" }, "filters": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "all", "today", "7d", "30d" ] } }, "required": [ "window" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "at:desc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "order", "shipped", "units", "warehouse", "store" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "timeEntries" }, "filters": { "type": "object", "properties": { "personId": { "anyOf": [ { "type": "string", "description": "A teamMembers id, e.g. \"teamMembers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "statuses": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "open", "closed", "needs_review", "forgotten" ] } }, "kinds": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "work", "break" ] } }, "sources": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "floor_device", "desk", "manager" ] } }, "window": { "type": "string", "enum": [ "all", "today", "7d", "30d" ] } }, "required": [ "personId", "statuses", "kinds", "sources", "window" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "start:desc", "start:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "person", "day", "in", "out", "kind", "minutes", "status", "flag", "source" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false }, { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "surface": { "type": "string", "const": "serials" }, "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 64 }, "variantId": { "anyOf": [ { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_stock", "packed", "shipped", "returned", "scrapped" ] }, { "type": "null" } ] } }, "required": [ "search", "variantId", "status" ], "additionalProperties": false }, "sort": { "anyOf": [ { "type": "string", "enum": [ "serial:asc" ] }, { "type": "null" } ] }, "columns": { "anyOf": [ { "maxItems": 24, "type": "array", "items": { "type": "string", "enum": [ "serial", "item", "status", "warehouse", "order" ] } }, { "type": "null" } ] } }, "required": [ "v", "surface", "filters", "sort", "columns" ], "additionalProperties": false } ], "description": "The view's envelope: the surface's filters, one of its sorts, its column ids." }, "shared": { "description": "true = every user of the shop sees and may edit it; omitted on an update keeps the owner.", "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The view's updatedAt the edit was made against; a moved view is refused." } }, "required": [ "name", "state" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/saved-views/delete": { "post": { "operationId": "saved_views_delete", "summary": "saved_views_delete", "description": "Soft-delete a saved view.\n\n**Operation id:** `saved_views_delete` — the same operation is `app.saved.views_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "savedViewId": { "type": "string", "description": "A savedViews id, e.g. \"savedViews_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The view's updatedAt the edit was made against; a moved view is refused." } }, "required": [ "savedViewId", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/saved-views/get": { "get": { "operationId": "saved_views_get", "summary": "saved_views_get", "description": "One saved view with its decoded state (filters, sort, columns) and the issues a stale or legacy view carries; null state means it cannot run as a view.\n\n**Operation id:** `saved_views_get` — the same operation is `app.saved.views_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "query", "parameters": [ { "name": "savedViewId", "in": "query", "required": true, "description": "A savedViews id, e.g. \"savedViews_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A savedViews id, e.g. \"savedViews_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/saved-views/rename": { "post": { "operationId": "saved_views_rename", "summary": "saved_views_rename", "description": "Rename a saved view without touching its filters.\n\n**Operation id:** `saved_views_rename` — the same operation is `app.saved.views_rename({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_rename`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "savedViewId": { "type": "string", "description": "A savedViews id, e.g. \"savedViews_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expectedRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The view's updatedAt the edit was made against; a moved view is refused." } }, "required": [ "savedViewId", "name", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/saved-views/share": { "post": { "operationId": "saved_views_share", "summary": "saved_views_share", "description": "Share a saved view with the whole shop, or make it private to the caller again.\n\n**Operation id:** `saved_views_share` — the same operation is `app.saved.views_share({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/saved_views_share`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "saved-views" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "savedViewId": { "type": "string", "description": "A savedViews id, e.g. \"savedViews_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "shared": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The view's updatedAt the edit was made against; a moved view is refused." } }, "required": [ "savedViewId", "shared", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/scan": { "get": { "operationId": "scan_resolve", "summary": "scan_resolve", "description": "Resolve a scanned code to what it means. Resolution order: bin barcode, bin code, variant barcode, alternate variant barcode, sku, then a printed pick list's batch number (#PK-…, the # and case optional), then a packing slip's code: a pack job's number (#PJ-…) or an allocation's (#AL-…, the slip printed before picking), which names the order's one pack job a packer still has work on. Returns {type: \"bin\"|\"variant\"|\"pick_batch\"|\"pack_job\"|\"ambiguous\"|\"none\"}; variant hits carry `matchedOn`; a pick_batch carries the batch's status and whose it is (mine, unclaimed, other); a pack_job its status. Bin codes are unique per WAREHOUSE, so pass warehouseId whenever the caller knows where it stands; a code that stays undecidable answers {type: \"ambiguous\"} with the candidates and a reason instead of guessing.\n\n**Operation id:** `scan_resolve` — the same operation is `app.scan.resolve({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/scan_resolve`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "scan" ], "x-operation-kind": "query", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "The scanned or typed code.", "schema": { "type": "string", "minLength": 1, "description": "The scanned or typed code." } }, { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse the scan happened in.", "schema": { "description": "document id of the warehouse the scan happened in.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/search": { "get": { "operationId": "search_global", "summary": "search_global", "description": "One search box across the identifiers people actually quote: order number or name, customer name or email, sku, barcode, tracking number and the short ids of shipments, returns, return requests and return receipts. At most 5 hits per type, each with a label, a sublabel and a suggested route. Every lookup is a bounded indexed prefix match — the customer match walks the 200 most recent orders (no index exists on the customer snapshot) and says so via `capped.customers`.\n\n**Operation id:** `search_global` — the same operation is `app.search.global({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/search_global`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "search" ], "x-operation-kind": "query", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Order number, customer, sku, barcode, tracking number or short id.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Order number, customer, sku, barcode, tracking number or short id." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials": { "get": { "operationId": "serials_list", "summary": "serials_list", "description": "List serial units by serial, 50 a page (the answer is { rows, capped, cursor } — pass `cursor` back to continue). `search` is the start of a serial (any case; a GS1 code's serial, AI 21, is read out), `variantId` one item's units, `status` one state (in_stock, packed, shipped, returned, scrapped). Each row: the serial, its state and since when, the item, the warehouse it is in or was last, and the order it last went to by name and number.\n\n**Operation id:** `serials_list` — the same operation is `app.serials.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/serials_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "query", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "The start of a serial number, any case; a GS1 code's serial (21) is read out.", "schema": { "description": "The start of a serial number, any case; a GS1 code's serial (21) is read out.", "type": "string", "maxLength": 256 } }, { "name": "variantId", "in": "query", "required": false, "description": "Only this item's units.", "schema": { "description": "Only this item's units.", "type": "string", "format": "floormode-id" } }, { "name": "status", "in": "query", "required": false, "description": "Only units in this state: in_stock, packed, shipped, returned or scrapped.", "schema": { "description": "Only units in this state: in_stock, packed, shipped, returned or scrapped.", "type": "string", "enum": [ "in_stock", "packed", "shipped", "returned", "scrapped" ] } }, { "name": "sort", "in": "query", "required": false, "description": "`serial:asc`, by serial (the only order).", "schema": { "description": "`serial:asc`, by serial (the only order).", "type": "string", "enum": [ "serial:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials/archived": { "get": { "operationId": "history_serial_ships", "summary": "history_serial_ships", "description": "Shipped serial units that left Floormode for the history archive (the serial book): every unit whose serial starts with q (a GS1 code is read for its serial), newest first, up to 50, each with its item, instant, warehouse and order (name and number). throughMonth is the newest month the book holds; serials_search answers the rest.\n\n**Operation id:** `history_serial_ships` — the same operation is `app.history.serial_ships({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/history_serial_ships`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "query", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "A serial, or its start, or a GS1 code carrying one.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A serial, or its start, or a GS1 code carrying one." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials/by-order": { "get": { "operationId": "serials_for_order", "summary": "serials_for_order", "description": "The serial numbers one order's shipped parcels carried: per unit its serial, item and parcel, from each parcel's serial list. capped when the order has more parcels or serials than one read walks.\n\n**Operation id:** `serials_for_order` — the same operation is `app.serials.for_order({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/serials_for_order`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "query", "parameters": [ { "name": "orderId", "in": "query", "required": true, "description": "document id of the order.", "schema": { "type": "string", "description": "document id of the order.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials/detail": { "get": { "operationId": "serials_get", "summary": "serials_get", "description": "Read one serial unit: the unit (serial, state, item, warehouse, how and when it was recorded and by whom), the receipt it came in on, its current or last parcel with the order's name and number (and the live order's id while Floormode holds it), the return it came back on, and its item's units per state (each counted up to 1,000, capped beyond). No customer data: read the order for that. Null for an unknown unit.\n\n**Operation id:** `serials_get` — the same operation is `app.serials.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/serials_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "query", "parameters": [ { "name": "serialUnitId", "in": "query", "required": true, "description": "document id of the serial unit.", "schema": { "type": "string", "description": "document id of the serial unit.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials/search": { "get": { "operationId": "serials_search", "summary": "serials_search", "description": "Find serial units by the start of their serial across every item, as serials_list with `search` alone: `q` any case, a GS1 code's serial (AI 21) read out. Same rows and paging. An unreadable code finds nothing.\n\n**Operation id:** `serials_search` — the same operation is `app.serials.search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/serials_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "query", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The start of a serial number, any case; a GS1 code's serial (21) is read out.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The start of a serial number, any case; a GS1 code's serial (21) is read out." } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/serials/set-status": { "post": { "operationId": "serials_set_status", "summary": "serials_set_status", "description": "Mark a serial unit scrapped by hand (`to: scrapped`, with a note): a unit that is in stock or back from a return but gone — the fix when a count finds fewer units than the serial units in stock. The note is kept on the unit's timeline. Refused as serial_scrapped for a unit already scrapped, illegal_transition for one packed or shipped. SIDE EFFECTS: none on stock; the count or adjustment moves the units.\n\n**Operation id:** `serials_set_status` — the same operation is `app.serials.set_status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/serials_set_status`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "serials" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialUnitId": { "type": "string", "description": "A serialUnits id, e.g. \"serialUnits_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "to": { "type": "string", "enum": [ "scrapped" ], "description": "\"scrapped\": the unit is gone (lost, broken)." }, "note": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, as the unit's history says it." } }, "required": [ "serialUnitId", "to", "note" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/settings": { "get": { "operationId": "settings_list", "summary": "settings_list", "description": "List every tenant setting with its current value, its description and whether the value is still the default. Every setting is a boolean, and the list is the authoritative one — it is the same closed set settings_set accepts, so read this before writing rather than guessing a name.\n\n**Operation id:** `settings_list` — the same operation is `app.settings.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/settings_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "settings_set", "summary": "settings_set", "description": "Set one tenant setting (all of them are booleans; settings_list describes each). TWO of the names do more than set a flag, and both effects are irreversible by setting the same flag back to false. (1) Enabling any peer connection (logistifiedConnectionEnabled, assemblifiedConnectionEnabled, alertifiedConnectionEnabled) starts that connection FRESH: nothing is queued for a switched-off peer, and any message it still held from before the switch went off is settled as not sent, never delivered late — the count comes back as `notSent`. (2) Enabling logistifiedConnectionEnabled means Logistified stops writing Shopify stock levels the moment receiving moves here, so it is REFUSED as a value (`{ ok: false, reason: \"warehouses_not_live\", warehouses, capped }`) while a receiving warehouse is not live: run 'Go live' (warehouses_applyCutover) there first; integrations_health.logistifiedSwitchBlockers lists those warehouses up front, and a successful call answers `{ ok: true, value }`. Switching the connection off later does NOT hand writing back (zero writers is the worse failure, and it is silent) — use integrations_health to see the current writer matrix. (3) Enabling a peer connection whose local stock was HANDED BACK reconnects it: the frozen rows return to the unplaced worklist as claims suggesting what this warehouse held at the handback, and those units leave our ledger, because the peer has owned them since it acknowledged the release — the count comes back as `localStockReclaimed`, and exactly one total is ever placed. (4) Switching a peer connection OFF is REFUSED (`conflict`) while that peer's local stock is still held here, or while a handback is already in flight: turning the flag off would leave those units counted in both apps with nothing sent, or end a release the other app has not confirmed yet. Call local_stock_disconnect instead — it hands the quantities back and writes this flag off itself once the peer confirms. (5) Switching a peer connection OFF is a seam exit (contracts 1.6.0): the peer is told it is being disconnected (a `peer_uninstalled` notice that leaves after the switch), and the switch is REFUSED (`conflict`, details.outstanding) — before anything is sent, every blocker named — while this shop still owes the peer something the switch cannot settle: a receiving agreement in which Logistified still delegates locations here (Logistified must release it first). Open Assemblified component pick batches do not refuse it: the switch CANCELS them first (picked units go back to their bins, `wo_pick_status: cancelled` goes to Assemblified; local_stock_status `openComponentBatches` counts them). A peer whose local stock is active while nothing of it is held here is released by the same switch (the ownership pin is cleared; the notice still names it), so switching the connection back ON reconnects it. Returns `{ ok: true, value: { name, value, notSent, localStockReclaimed } }` on success, `{ ok: false, reason: \"warehouses_not_live\", detail, warehouses, capped }` when the Logistified switch is refused; every other refusal is a conflict error.\n\n**Operation id:** `settings_set` — the same operation is `app.settings.set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/settings_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "autoHoldHighRisk", "logistifiedConnectionEnabled", "assemblifiedConnectionEnabled", "alertifiedConnectionEnabled", "autoAssignPickTasks", "autoReplenishOnPick", "domRoutingEnabled" ], "description": "Which setting to write. Closed set — see settings_list for what each one does." }, "value": { "type": "boolean", "description": "The new value. Every tenant setting is a boolean." } }, "required": [ "name", "value" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/settings/delivery-dates": { "get": { "operationId": "delivery_dates_settings_get", "summary": "delivery_dates_settings_get", "description": "Get the delivery-date mapping: which order attribute holds the customer's requested delivery day (`source`: key and format), the store's time zone, the `revision` an edit must name, whether delivery dates are on (`active`), and the re-derive of open orders after a change (`rederive`: idle, running or parked, with the orders read and rewritten so far). Off by default.\n\n**Operation id:** `delivery_dates_settings_get` — the same operation is `app.delivery.dates_settings_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/delivery_dates_settings_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "delivery_dates_settings_set", "summary": "delivery_dates_settings_set", "description": "Replace the delivery-date mapping: `source` (the attribute key, matched case-insensitively, and its format; null switches delivery dates off) and the store's IANA `timeZone`, which a source needs (refused with time_zone_required otherwise). Fenced on `expectedRevision` (a stale edit is refused with revision_mismatch); saving what is stored changes nothing. A change that leaves a source set (a new key or format, or a moved time zone) re-derives the requested delivery day of every OPEN order in the background (the deliveryDayRederive job; `rederiveArmed`); closed orders keep theirs. Switching off rewrites nothing. While a source is set, open work with a requested day is due at the end of its pack day (see orders_work_queue).\n\n**Operation id:** `delivery_dates_settings_set` — the same operation is `app.delivery.dates_settings_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/delivery_dates_settings_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The revision the edit started from; a stale one is refused." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "attribute" ] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The order attribute that holds the day, e.g. \"Delivery Date\"; matched case-insensitively." }, "format": { "type": "string", "enum": [ "auto", "iso", "ymd_slash", "dmy_slash", "mdy_slash", "dmy_dot", "month_name" ], "description": "How the value is written. \"auto\" reads only unambiguous dates (2026-10-17, 2026/10/17, month names); a numeric day-month date needs dmy_slash, mdy_slash or dmy_dot." } }, "required": [ "kind", "key", "format" ] }, { "type": "null" } ], "description": "Where the day is read from; null switches delivery dates off." }, "timeZone": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "The store's IANA time zone (e.g. \"Europe/London\"); required with a source." } }, "required": [ "expectedRevision", "source", "timeZone" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/settings/delivery-dates/preview": { "post": { "operationId": "delivery_dates_preview", "summary": "delivery_dates_preview", "description": "Preview a draft delivery-date mapping on recent orders without saving it: the attribute keys the newest orders carry (`keys`, with how many of up to 20 sampled orders carry each), the proposed date-picker key (`suggestedKey`), and with a draft key what it would read: parsed / none / unreadable counts and up to five examples. An example's value as written (`raw`) needs orders.view as well; `capped` says the newest two hundred orders held fewer than 20 with attributes.\n\n**Operation id:** `delivery_dates_preview` — the same operation is `app.delivery.dates_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/delivery_dates_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "attribute" ] }, "key": { "description": "The draft key; without one only the keys on recent orders are listed.", "type": "string", "minLength": 1, "maxLength": 100 }, "format": { "type": "string", "enum": [ "auto", "iso", "ymd_slash", "dmy_slash", "mdy_slash", "dmy_dot", "month_name" ], "description": "How the value is written. \"auto\" reads only unambiguous dates (2026-10-17, 2026/10/17, month names); a numeric day-month date needs dmy_slash, mdy_slash or dmy_dot." } }, "required": [ "kind", "format" ] }, "timeZone": { "description": "The draft's store time zone; absent = the saved one, else UTC.", "type": "string", "maxLength": 64 } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/settings/packing-slip": { "get": { "operationId": "packing_slip_settings_get", "summary": "packing_slip_settings_get", "description": "Get the packing slip settings: whether the slip prints each line's lots and dates (`printLots`, on by default), its serial numbers (`printSerials`, on) and a bundle's components' lots (`printComponentLots`, off); whether the lots a parcel shipped are written to its Shopify order as the metafield floormode.fulfilment_lots when Shopify confirms the fulfilment (`orderMetafield`, off); whether the label-size delivery note is offered (`labelNote`, off); and the `revision` an edit must name.\n\n**Operation id:** `packing_slip_settings_get` — the same operation is `app.packing.slip_settings_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_slip_settings_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "packing_slip_settings_set", "summary": "packing_slip_settings_set", "description": "Replace the packing slip settings (see packing_slip_settings_get), fenced on `expectedRevision` (a stale edit is refused with revision_mismatch); saving what is stored changes nothing. Turning `orderMetafield` on writes one line per lot (item, lot, date; no customer data) to the Shopify order of every parcel confirmed from then on, replacing the order's value when a later parcel ships more lots; orders already fulfilled are not written. Uses the granted write_orders scope.\n\n**Operation id:** `packing_slip_settings_set` — the same operation is `app.packing.slip_settings_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/packing_slip_settings_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "settings" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "printLots": { "type": "boolean", "description": "print each line's lots and their dates under it." }, "printSerials": { "type": "boolean", "description": "print each line's serial numbers under it." }, "printComponentLots": { "type": "boolean", "description": "print the lots of a bundle's components too (off: the bundle prints none)." }, "orderMetafield": { "type": "boolean", "description": "write the order's lots to its Shopify order (metafield floormode.fulfilment_lots) when a parcel's fulfilment is confirmed." }, "labelNote": { "type": "boolean", "description": "offer the label-size delivery note for a label printer (format=label)." }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "the revision the settings were read at; refused revision_mismatch when it moved." } }, "required": [ "printLots", "printSerials", "printComponentLots", "orderMetafield", "labelNote", "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/setup": { "get": { "operationId": "setup_status", "summary": "setup_status", "description": "Home's setup guide: every warehouse that is not live with its detected steps (bins, stock, live) and next step, the live / in-setup counts, the Shopify locations a warehouse can still be made from (suggested ones first), the store import's state and whether a plan is needed. Nothing is remembered: everything is re-detected on read.\n\n**Operation id:** `setup_status` — the same operation is `app.setup.status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/setup_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "setup" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments": { "get": { "operationId": "shipments_list", "summary": "shipments_list", "description": "List shipments, in the chosen order (`sort`; newest first by default), one page, with the order name and carrier label. Filter by one or more statuses (draft, rated, purchasing, purchased, in_transit, delivered, exception, voided, refund_pending), by the order they belong to, or to the shipments whose checkout option's mapped service the carrier did not offer (`rateFallbackOnly`; voided ones left out).\n\n**Operation id:** `shipments_list` — the same operation is `app.shipments.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "query", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "draft", "rated", "purchasing", "purchased", "in_transit", "delivered", "exception", "voided", "refund_pending" ] } } }, { "name": "orderId", "in": "query", "required": false, "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A orders id, e.g. \"orders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "fulfillmentOrderId", "in": "query", "required": false, "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "rateFallbackOnly", "in": "query", "required": false, "description": "Only shipments whose rates lacked the service their checkout option is mapped to (`rateFallback: not_offered`), voided ones left out. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only shipments whose rates lacked the service their checkout option is mapped to (`rateFallback: not_offered`), voided ones left out.", "type": "boolean" } }, { "name": "store", "in": "query", "required": false, "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "schema": { "description": "Only this store's rows: a store id from `stores_list`. Refused while the account has one store.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "shipments_create_draft", "summary": "shipments_create_draft", "description": "Open a draft shipment for an order (optionally scoped to one fulfillment order) against a connected carrier account. Without `carrierAccountId` the account is chosen: the one the parcel's checkout option is mapped to when it is an active parcel account that can ship there, else the first such account by label; none refuses with `conflict` `code: no_carrier_account`. The answer names the account and how it was chosen (`draftAccountSource`: `explicit`, `mapped`, `default`). The mode and tracking type come from the carrier account; the Worker then rate-shops and buys it. A parcel that crosses a customs border (outside the EU VAT area, or between two other territories) starts with its declaration pre-filled from its contents: the pack job's scanned units, else the fulfillment order's lines, each with the product's HS code and country of origin from Shopify, its unit weight and the paid unit value. `customsItems` replaces the pre-fill. One OPEN draft per fulfillment order: while a shipment for that fulfillment order is still draft/rated/purchasing, a second draft is refused with `conflict` (`code: open_draft_exists`, `shipmentId` of the live one) — rate or buy that one. A pickup, local-delivery or other non-shipping fulfillment order (or an order with no shipping fulfillment order at all) gets no label: `conflict` with `code: not_a_shipping_order` and its `deliveryMethod`; shipments_claimPurchase refuses the same way, so no label is ever bought for one. A cancelled order gets no draft (`conflict`, `code: cancelled`): its draft and rated shipments close when Shopify cancels it.\n\n**Operation id:** `shipments_create_draft` — the same operation is `app.shipments.create_draft({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_create_draft`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "description": "document id of the order.", "format": "floormode-id" }, "fulfillmentOrderId": { "description": "document id of the fulfillment order.", "type": "string", "format": "floormode-id" }, "packJobId": { "description": "The pack job this parcel is; its weighed package rates the shipment (B-0005).", "type": "string", "format": "floormode-id" }, "carrierAccountId": { "description": "document id of the carrier account; absent = the mapped account, else the first reachable one.", "type": "string", "format": "floormode-id" }, "customsItems": { "description": "The declaration lines, one per item of the parcel: description, quantity, unit value and currency, net weight of one unit in grams, HS code (6 to 13 digits), ISO country of origin, and the item it came from (variantId). Replaces the stored lines.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "hsCode": { "type": "string", "maxLength": 32, "description": "Harmonized System tariff code: 6 to 13 digits." }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "value": { "type": "number", "minimum": 0, "description": "Unit value in `currency`." }, "currency": { "type": "string", "minLength": 1 }, "netWeightGrams": { "type": "number", "minimum": 0, "description": "Net weight of ONE unit, in grams." }, "originCountry": { "type": "string", "maxLength": 32, "description": "ISO alpha-2 country of manufacture." }, "variantId": { "description": "The item this line came from, as shipments.get lists it; send it back, or the line counts as typed and loses its item.", "type": "string", "format": "floormode-id" } }, "required": [ "hsCode", "description", "quantity", "value", "currency", "netWeightGrams", "originCountry" ] } }, "iossNumber": { "description": "IOSS number, only for goods sent from outside the EU into it (≤ €150). No connected carrier sends it yet, so a rate or label request carrying one is refused.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "incoterm": { "description": "DAP = recipient pays; DDP = seller prepays. Sent by EasyPost.", "anyOf": [ { "type": "string", "enum": [ "DAP", "DDP" ] }, { "type": "null" } ] }, "dutyPayment": { "description": "Who pays duties. No connected carrier sends it yet; a request carrying it is refused.", "anyOf": [ { "type": "string", "enum": [ "SENDER", "RECEIVER", "THIRD_PARTY" ] }, { "type": "null" } ] } }, "required": [ "orderId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/bulk-purchase": { "post": { "operationId": "shipments_bulk_purchase", "summary": "shipments_bulk_purchase", "description": "Buy the labels of up to 100 shipments in one run: name the shipments, or the fulfillment orders whose draft or rated shipment to buy. The run buys them one at a time in the background; `rows` are the per-shipment outcomes at opening (`pending`, `replayed` for a label that already exists, `refused` with a `code`), `jobId` reads the progress through shipments.bulk_purchase_status. `requestKey` replays the same run on a retry; `serviceId` forces one carrier service, otherwise the shipping rules or the cheapest rate decide. Each label is a paid carrier purchase. A purchase the carrier never answered is retried on the SAME carrier key with exactly the first rate, parcel and carrier account; if any of them changed meanwhile (new rules, a new weight, replaced or sandbox-flipped credentials) the row is refused with `purchase_payload_changed`, and a claim from before payloads were bound, or on a direct carrier, with `purchase_reconciliation_required`. Neither buys again: check the shipment at the carrier and answer with shipments.resolvePurchase (no label was created, or record the label found there), then buy once more if no label exists. A shipment of a pickup, local-delivery or other non-shipping order is refused at opening with `not_a_shipping_order` (final, never retried) and the refusal is recorded on the shipment's timeline. A draft or rated shipment of a closed order is refused at opening and again before its batch reaches the carrier, recorded on its timeline: `cancelled` (Shopify cancelled the order; its unbought shipments close), `cancel_pending` (a cancel Floormode asked for holds the order) or `order_fulfilled`. A shipment whose carrier account cannot reach its destination, cannot carry its dangerous goods, or whose required customs declaration has gaps, is skipped before any carrier call with `carrier_cannot_reach` / `carrier_cannot_carry_dg` / `customs_incomplete` and the sentence naming what is missing and the way out.\n\n**Operation id:** `shipments_bulk_purchase` — the same operation is `app.shipments.bulk_purchase({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_bulk_purchase`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentIds": { "description": "Shipments to buy a label for (1 to 100).", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "description": "A shipments id, e.g. \"shipments_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "fulfillmentOrderIds": { "description": "Fulfillment orders whose open draft or rated shipment to buy (1 to 100).", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "description": "A fulfillmentOrders id, e.g. \"fulfillmentOrders_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Caller-minted key, one per logical request and kept across retries: the same key with the same arguments replays the first answer; with other arguments it is refused." }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 100, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "requestKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/bulk-purchase/status": { "get": { "operationId": "shipments_bulk_purchase_status", "summary": "shipments_bulk_purchase_status", "description": "Read one bulk purchase run: every shipment with its outcome (`pending`, `purchased`, `replayed`, `refused` with `code` and `detail`), the tally and `finishedAt` once no shipment is pending. Null for an unknown run. A refused row's `code` is the refusing door's own: `purchase_payload_changed` (the retry would not buy what the first attempt did) and `purchase_reconciliation_required` (a label may already exist) both mean: check the shipment at the carrier and answer with shipments.resolvePurchase before buying again; `purchase_unresolved` means the carrier never answered twice.\n\n**Operation id:** `shipments_bulk_purchase_status` — the same operation is `app.shipments.bulk_purchase_status({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_bulk_purchase_status`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "query", "parameters": [ { "name": "jobId", "in": "query", "required": true, "description": "A bulkPurchaseJobs id, e.g. \"bulkPurchaseJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A bulkPurchaseJobs id, e.g. \"bulkPurchaseJobs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/customs": { "post": { "operationId": "shipments_set_customs", "summary": "shipments_set_customs", "description": "Set the customs declaration of a draft/rated shipment (SHP-007): the lines (`customsItems` replaces them; `refill: true` derives them again from the parcel's contents and the products' Shopify HS codes and origins), the IOSS number, the incoterm (DAP/DDP) and who pays duties. A rated shipment returns to `draft` with its rates dropped, so the declaration that is bought is the one that was rated: get rates again. While a required declaration has gaps (no line, a line without description, quantity, value or net weight above 0, an HS code that is not 6 to 13 digits, an origin that is not an ISO alpha-2 code) the rate route and shipments_claimPurchase refuse with `conflict` `code: customs_incomplete`; a carrier account that cannot reach the destination is refused with `code: carrier_cannot_reach`, one that cannot carry the parcel's dangerous goods with `code: carrier_cannot_carry_dg`. All before any carrier call; shipments.get publishes the same verdict (`labelRefusal`) and the route (`route`). The carrier generates the customs documents (CN23, invoice); they are stored with the label. Rejected once a label is purchased. On a cancelled order's shipment nothing is declared: the order's draft and rated shipments close instead, and the answer is `status: voided`.\n\n**Operation id:** `shipments_set_customs` — the same operation is `app.shipments.set_customs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_set_customs`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentId": { "type": "string", "description": "document id of the shipment.", "format": "floormode-id" }, "customsItems": { "description": "The declaration lines, one per item of the parcel: description, quantity, unit value and currency, net weight of one unit in grams, HS code (6 to 13 digits), ISO country of origin, and the item it came from (variantId). Replaces the stored lines.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "hsCode": { "type": "string", "maxLength": 32, "description": "Harmonized System tariff code: 6 to 13 digits." }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "value": { "type": "number", "minimum": 0, "description": "Unit value in `currency`." }, "currency": { "type": "string", "minLength": 1 }, "netWeightGrams": { "type": "number", "minimum": 0, "description": "Net weight of ONE unit, in grams." }, "originCountry": { "type": "string", "maxLength": 32, "description": "ISO alpha-2 country of manufacture." }, "variantId": { "description": "The item this line came from, as shipments.get lists it; send it back, or the line counts as typed and loses its item.", "type": "string", "format": "floormode-id" } }, "required": [ "hsCode", "description", "quantity", "value", "currency", "netWeightGrams", "originCountry" ] } }, "iossNumber": { "description": "IOSS number, only for goods sent from outside the EU into it (≤ €150). No connected carrier sends it yet, so a rate or label request carrying one is refused.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "incoterm": { "description": "DAP = recipient pays; DDP = seller prepays. Sent by EasyPost.", "anyOf": [ { "type": "string", "enum": [ "DAP", "DDP" ] }, { "type": "null" } ] }, "dutyPayment": { "description": "Who pays duties. No connected carrier sends it yet; a request carrying it is refused.", "anyOf": [ { "type": "string", "enum": [ "SENDER", "RECEIVER", "THIRD_PARTY" ] }, { "type": "null" } ] }, "refill": { "description": "Derive the lines again from the parcel's contents; excludes customsItems.", "type": "boolean" } }, "required": [ "shipmentId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/discard": { "post": { "operationId": "shipments_discard_draft", "summary": "shipments_discard_draft", "description": "Discard a draft or rated shipment nobody bought: it becomes voided (nothing is refunded, no label existed) and its parcel can be drafted again with any carrier account. Refused once a purchase is claimed; void the label instead.\n\n**Operation id:** `shipments_discard_draft` — the same operation is `app.shipments.discard_draft({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_discard_draft`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentId": { "type": "string", "description": "document id of the shipment.", "format": "floormode-id" } }, "required": [ "shipmentId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/get": { "get": { "operationId": "shipments_get", "summary": "shipments_get", "description": "Get one shipment with its rate-shopping list, chosen rate, tracking, documents (labels/BOL/customs forms) and its canonical tracker, plus where it goes (`route`: origin and destination country, ship-to city, whether a customs declaration is required, whether an IOSS number can apply), the parcel's dangerous goods as last derived (`shipment.dangerousGoods`: strictest class, classes, UN numbers, items; null when nothing in it is marked) and why no label could be rated or bought as it stands (`labelRefusal`: `carrier_cannot_reach`, `carrier_cannot_carry_dg` or `customs_incomplete`, null otherwise). `rateDecision` is the default decided with the stored rates: `defaultRateId`, its `basis` (`checkout_option` — the customer's mapped checkout option —, `rule`, `cheapest`, `none`), the rule's name, the checkout option and its mapping revision, and a `fallback` when the mapped service did not decide (`not_offered`: the carrier did not quote it; `other_account`: drafted on another account than the mapping). `ratesStale` with `ratesStaleReason` (`ship_to_changed`, `shipping_option_changed`): the stored rates may not be bought, get rates again. `mappingChanged`: the option's mapping moved since the decision; nothing is refused.\n\n**Operation id:** `shipments_get` — the same operation is `app.shipments.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "query", "parameters": [ { "name": "shipmentId", "in": "query", "required": true, "description": "document id of the shipment.", "schema": { "type": "string", "description": "document id of the shipment.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/refresh-tracking": { "post": { "operationId": "shipments_refresh_tracking", "summary": "shipments_refresh_tracking", "description": "Queue a manual tracking refresh for a purchased, in-transit, delivered or exception direct-carrier shipment. Requires an active connected carrier account and tracking number. Pending requests are deduplicated; refreshes are limited to one per minute. The durable result updates the canonical shipment tracker. A direct carrier whose tracking Floormode does not read (DPD Germany) answers `declined: \"tracking_not_connected\"` with its sentence and queues nothing.\n\n**Operation id:** `shipments_refresh_tracking` — the same operation is `app.shipments.refresh_tracking({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_refresh_tracking`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentId": { "type": "string", "description": "A shipments id, e.g. \"shipments_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "shipmentId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipments/resolve-purchase": { "post": { "operationId": "shipments_resolvePurchase", "summary": "shipments_resolvePurchase", "description": "Answer a label purchase that did not finish, after checking the carrier. A carrier that never answered leaves the shipment `purchasing`, because a label may exist; a direct carrier, a claim from before payloads were bound or an open `purchase_reconciliation_required` exception is never retried by itself. `resolution.outcome`: `no_label` (none was created, or it was cancelled at the carrier) makes the shipment `rated` again, to be bought once more (`voided` when Shopify cancelled its order meanwhile: it closes, and the answer's `status` says so); `label_exists` records the label with its `trackingId` (and optional `carrierShipmentId`) at the rate and cost the attempt was for, with no documents (print it from the carrier), and the shipment is `purchased`, its tracking going to the Shopify fulfillment as for any bought label. Either answer resolves the shipment's open purchase exceptions; an optional `note` (500 characters) lands on its timeline with the member who answered. Refused with `conflict`: `purchase_not_pending` (the shipment is not `purchasing`), `effect_in_flight` (the attempt is under 5 minutes old) or `purchase_retry_available` (buying again with the first rate settles it). shipments.get publishes when it is admitted (`purchaseResolution`). Irreversible: a wrong `no_label` may pay for two labels.\n\n**Operation id:** `shipments_resolvePurchase` — the same operation is `app.shipments.resolvePurchase({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipments_resolvePurchase`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipments" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentId": { "type": "string", "description": "A shipments id, e.g. \"shipments_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "resolution": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "const": "no_label" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "outcome" ], "additionalProperties": false, "description": "No label exists at the carrier: none was created, or it was cancelled there." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "label_exists" }, "trackingId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The label's tracking number at the carrier.", "format": "floormode-id" }, "carrierShipmentId": { "description": "The carrier's own shipment or parcel id, when it shows one.", "type": "string", "minLength": 1, "maxLength": 100, "format": "floormode-id" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "outcome", "trackingId" ], "additionalProperties": false, "description": "A label exists at the carrier: it is recorded as this shipment's purchase." } ] } }, "required": [ "shipmentId", "resolution" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipping-rules": { "get": { "operationId": "shipping_rules_list", "summary": "shipping_rules_list", "description": "List the tenant's shipping rules in cascade (position) order. Each rule has conditions (destinationCountry, shippingOption, weight, total, sku, channel, dangerousGoods), matchAll (AND/OR) and an action (assign_service pins a carrier/service, cheapest_rate takes the cheapest rate, downgrade_service the cheapest non-express rate). Applied when a shipment's rates are recorded, unless the parcel's checkout option is mapped to a service the carrier quoted: the first enabled rule that matches and yields a rate picks the default, the cheapest priced rate is the fallback. Answers `{ rows, capped, cursor: null }`: create refuses the 101st live rule, and `capped: true` means a cascade from before that ceiling is longer than the page — rate selection then offers no default when no listed rule matched.\n\n**Operation id:** `shipping_rules_list` — the same operation is `app.shipping.rules_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipping_rules_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipping-rules" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "shipping_rules_create", "summary": "shipping_rules_create", "description": "Create a shipping rule. It is added at the end of the cascade and enabled by default. An assign_service rule with no conditions is a preset (a saved carrier+service applied to every order).\n\n**Operation id:** `shipping_rules_create` — the same operation is `app.shipping.rules_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipping_rules_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipping-rules" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "conditions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "destinationCountry", "shippingOption", "weight", "total", "sku", "channel", "dangerousGoods", "tag" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "description": "`neq` and `in` take a comma-separated list. For `shippingOption` (the customer's checkout option), `eq` / `neq` / `in` take ids from checkout_options_list and `contains` matches the title; `gt` / `lt` are refused, and a rule with this condition is skipped while the order's option is unknown. For `dangerousGoods` (the classes the order's or the parcel's items are marked with; `none` when it holds none), `eq` / `neq` / `in` take class keys (lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated, none); `contains`, `gt` and `lt` are refused." } }, "matchAll": { "type": "boolean" }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "assign_service" }, "params": { "type": "object", "properties": { "carrier": { "type": "string" }, "service": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "cheapest_rate" }, "params": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "downgrade_service" }, "params": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "type", "params" ] } ], "description": "Discriminated on `type`: assign_service {carrier?, service?} (a preset when the rule has no conditions); cheapest_rate (the cheapest rate) / downgrade_service (the cheapest non-express rate) take {}. No action reads fulfillBy, a ship-by deadline." }, "enabled": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "name", "conditions", "matchAll", "action" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipping-rules/delete": { "post": { "operationId": "shipping_rules_delete", "summary": "shipping_rules_delete", "description": "Soft-delete a shipping rule; it stops being evaluated immediately.\n\n**Operation id:** `shipping_rules_delete` — the same operation is `app.shipping.rules_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipping_rules_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipping-rules" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipping-rules/reorder": { "post": { "operationId": "shipping_rules_reorder", "summary": "shipping_rules_reorder", "description": "Move a shipping rule one slot up or down the cascade (rules evaluate in position order, lowest first, first match wins). Returns moved:false when already at the end.\n\n**Operation id:** `shipping_rules_reorder` — the same operation is `app.shipping.rules_reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipping_rules_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipping-rules" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "direction": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "ruleId", "direction" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shipping-rules/update": { "post": { "operationId": "shipping_rules_update", "summary": "shipping_rules_update", "description": "Update a shipping rule. Any field may be changed independently — pass only what you want to change (e.g. enabled to toggle the rule on or off).\n\n**Operation id:** `shipping_rules_update` — the same operation is `app.shipping.rules_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shipping_rules_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shipping-rules" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "document id of the shipping rule.", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "conditions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "destinationCountry", "shippingOption", "weight", "total", "sku", "channel", "dangerousGoods", "tag" ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "in" ] }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "description": "`neq` and `in` take a comma-separated list. For `shippingOption` (the customer's checkout option), `eq` / `neq` / `in` take ids from checkout_options_list and `contains` matches the title; `gt` / `lt` are refused, and a rule with this condition is skipped while the order's option is unknown. For `dangerousGoods` (the classes the order's or the parcel's items are marked with; `none` when it holds none), `eq` / `neq` / `in` take class keys (lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated, none); `contains`, `gt` and `lt` are refused." } }, "matchAll": { "type": "boolean" }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "assign_service" }, "params": { "type": "object", "properties": { "carrier": { "type": "string" }, "service": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "cheapest_rate" }, "params": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "type", "params" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "downgrade_service" }, "params": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "type", "params" ] } ], "description": "Discriminated on `type`: assign_service {carrier?, service?} (a preset when the rule has no conditions); cheapest_rate (the cheapest rate) / downgrade_service (the cheapest non-express rate) take {}. No action reads fulfillBy, a ship-by deadline." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/shopify-locations": { "get": { "operationId": "shopify_locations_list", "summary": "shopify_locations_list", "description": "List the mirrored Shopify locations of the authenticated tenant (max 100). This is the Shopify location MIRROR, not the internal topology tree: `/locations` and `locations_*` are the warehouse's bins/racks/zones.\n\n**Operation id:** `shopify_locations_list` — the same operation is `app.shopify.locations_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/shopify_locations_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "shopify-locations" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sku-slotting": { "get": { "operationId": "sku_slotting_list", "summary": "sku_slotting_list", "description": "List the per-SKU slotting records of a warehouse (max 200): the fixed home bin, the min/max replenishment thresholds, the computed abcClass and the last-reslot timestamp, hydrated with sku, variant title and home bin code.\n\n**Operation id:** `sku_slotting_list` — the same operation is `app.sku.slotting_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sku_slotting_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sku-slotting" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "sku_slotting_set", "summary": "sku_slotting_set", "description": "Create or update a variant's per-SKU slotting record in a warehouse (idempotent on variant + warehouse). homeLocationId (null clears) must belong to the warehouse and feeds the directed-putaway home-first step; minQty/maxQty are the replenishment thresholds; abcClass (null clears) the velocity class. Omitted fields keep their stored value.\n\n**Operation id:** `sku_slotting_set` — the same operation is `app.sku.slotting_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sku_slotting_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sku-slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "homeLocationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "minQty": { "type": "number", "minimum": 0 }, "maxQty": { "type": "number", "minimum": 0 }, "abcClass": { "anyOf": [ { "type": "string", "enum": [ "A", "B", "C" ] }, { "type": "null" } ] } }, "required": [ "variantId", "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sku-slotting/delete": { "post": { "operationId": "sku_slotting_delete", "summary": "sku_slotting_delete", "description": "Delete a per-SKU slotting record by document id.\n\n**Operation id:** `sku_slotting_delete` — the same operation is `app.sku.slotting_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sku_slotting_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sku-slotting" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skuSlottingId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "skuSlottingId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sku-slotting/get": { "get": { "operationId": "sku_slotting_get", "summary": "sku_slotting_get", "description": "Get one variant's per-SKU slotting record in a warehouse, or null.\n\n**Operation id:** `sku_slotting_get` — the same operation is `app.sku.slotting_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sku_slotting_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sku-slotting" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/abc": { "get": { "operationId": "slotting_abc_velocity", "summary": "slotting_abc_velocity", "description": "ABC velocity of a warehouse's SKUs (top 200 by pick volume) from the pick ledger over a window (default 90 days): each row carries sku, picks and the A/B/C class (A = top ~80% of picks). `capped` discloses a truncated ledger scan.\n\n**Operation id:** `slotting_abc_velocity` — the same operation is `app.slotting.abc_velocity({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_abc_velocity`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "windowDays", "in": "query", "required": false, "description": "Analysis window; defaults to 90, cut to the days the pick ledger keeps (history_status tier.days). The answer's windowDays is the window used.", "schema": { "description": "Analysis window; defaults to 90, cut to the days the pick ledger keeps (history_status tier.days). The answer's windowDays is the window used.", "type": "integer", "minimum": 1, "maximum": 400 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/assign-abc": { "post": { "operationId": "slotting_assign_abc", "summary": "slotting_assign_abc", "description": "Compute ABC velocity and stamp the class onto the per-SKU records (creating a minimal row where none exists). Feeds the abcClass rule predicate + the T5 replenishment inputs. Bounded (top 1000 by pick volume) + cap-disclosed. Returns created/updated/unchanged counts.\n\n**Operation id:** `slotting_assign_abc` — the same operation is `app.slotting.assign_abc({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_assign_abc`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "windowDays": { "description": "Analysis window; defaults to 90, cut to the days the pick ledger keeps (history_status tier.days). The answer's windowDays is the window used.", "type": "integer", "minimum": 1, "maximum": 400 } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/reslot": { "get": { "operationId": "slotting_reslot_suggestions", "summary": "slotting_reslot_suggestions", "description": "Re-slotting suggestions (suggestion-only, WHT-014): SKUs whose current primary slot's golden-zone band diverges from the band their velocity deserves (an A-class SKU stuck in the far third). Each row carries the current bin, its pick-sequence band and the ideal band. Bounded + cap-disclosed. Materialize the top ones with slotting_create_reslot_tasks.\n\n**Operation id:** `slotting_reslot_suggestions` — the same operation is `app.slotting.reslot_suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_reslot_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "windowDays", "in": "query", "required": false, "description": "Analysis window; defaults to 90, cut to the days the pick ledger keeps (history_status tier.days). The answer's windowDays is the window used.", "schema": { "description": "Analysis window; defaults to 90, cut to the days the pick ledger keeps (history_status tier.days). The answer's windowDays is the window used.", "type": "integer", "minimum": 1, "maximum": 400 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/reslot-tasks": { "post": { "operationId": "slotting_create_reslot_tasks", "summary": "slotting_create_reslot_tasks", "description": "Materialize re-slotting suggestions as move tasks (M10 T3) for human approval (WHT-014, max 50 variants). For each variant it finds the current primary slot, resolves where the slotting rules would place it and — when that differs — creates a deduped `move` task (refType slotting) from the current bin to the target. Suggestion-only: it creates review tasks, never moves stock. Variants with no slot / no target / an existing task are skipped.\n\n**Operation id:** `slotting_create_reslot_tasks` — the same operation is `app.slotting.create_reslot_tasks({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_create_reslot_tasks`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "variantIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "document ids of the variants." } }, "required": [ "warehouseId", "variantIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/rules": { "get": { "operationId": "slotting_rules_list", "summary": "slotting_rules_list", "description": "List a warehouse's slotting rules in cascade (position) order. Each is an ordered predicate→target row (first match wins at putaway): the predicate tests the SKU (category, abcClass, temperature, hazmat, weightRange, sizeRange) and the target directs it (zoneId, locationTypeId or homeLocationId). An empty rule set ⇒ today's nearest-available directed putaway (no regression).\n\n**Operation id:** `slotting_rules_list` — the same operation is `app.slotting.rules_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_rules_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "document id of the warehouse.", "schema": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "slotting_rules_create", "summary": "slotting_rules_create", "description": "Create a slotting rule in a warehouse (appended last in the cascade). mode is fixed (one pinned home) or dynamic (the ruled zone/type, ranked at putaway). Target references must belong to the warehouse; an empty predicate is a catch-all default rule.\n\n**Operation id:** `slotting_rules_create` — the same operation is `app.slotting.rules_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_rules_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1 }, "predicate": { "type": "object", "properties": { "category": { "description": "Product type match (case-insensitive).", "type": "string" }, "abcClass": { "type": "string", "enum": [ "A", "B", "C" ] }, "temperature": { "type": "string", "enum": [ "ambient", "chilled", "frozen" ] }, "hazmat": { "type": "boolean" }, "weightRange": { "description": "Unit weight band in grams.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "sizeRange": { "description": "Largest unit dimension band in mm.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } } }, "description": "SKU test; every declared dimension must hold (AND). Empty ⇒ matches every SKU." }, "target": { "type": "object", "properties": { "zoneId": { "description": "document id of the target zone.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "locationTypeId": { "description": "document id of the location type.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "homeLocationId": { "description": "document id of a fixed home bin.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "description": "Where a matched SKU is directed; each field independently optional." }, "enabled": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "warehouseId", "name", "predicate", "target" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/rules/delete": { "post": { "operationId": "slotting_rules_delete", "summary": "slotting_rules_delete", "description": "Soft-delete a slotting rule.\n\n**Operation id:** `slotting_rules_delete` — the same operation is `app.slotting.rules_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_rules_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/rules/reorder": { "post": { "operationId": "slotting_rules_reorder", "summary": "slotting_rules_reorder", "description": "Move a slotting rule one slot up or down its warehouse cascade by swapping positions (lower position is evaluated first).\n\n**Operation id:** `slotting_rules_reorder` — the same operation is `app.slotting.rules_reorder({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_rules_reorder`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "direction": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "ruleId", "direction" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/slotting/rules/update": { "post": { "operationId": "slotting_rules_update", "summary": "slotting_rules_update", "description": "Update a slotting rule: name, enabled, predicate, target (re-validated against the warehouse) or mode. Only the fields you pass change.\n\n**Operation id:** `slotting_rules_update` — the same operation is `app.slotting.rules_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/slotting_rules_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "slotting" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "predicate": { "type": "object", "properties": { "category": { "description": "Product type match (case-insensitive).", "type": "string" }, "abcClass": { "type": "string", "enum": [ "A", "B", "C" ] }, "temperature": { "type": "string", "enum": [ "ambient", "chilled", "frozen" ] }, "hazmat": { "type": "boolean" }, "weightRange": { "description": "Unit weight band in grams.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "sizeRange": { "description": "Largest unit dimension band in mm.", "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } } }, "description": "SKU test; every declared dimension must hold (AND). Empty ⇒ matches every SKU." }, "target": { "type": "object", "properties": { "zoneId": { "description": "document id of the target zone.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "locationTypeId": { "description": "document id of the location type.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "homeLocationId": { "description": "document id of a fixed home bin.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "description": "Where a matched SKU is directed; each field independently optional." } }, "required": [ "ruleId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations": { "get": { "operationId": "stations_list", "summary": "stations_list", "description": "List a warehouse's stations (max 200): the routing depots + fixed work points. Each has a kind (pack, receive, qc, count, ship, production), code, name, optional travel coordinates (x/y/z) and its active flag. Filter by warehouse and/or kind; inactive hidden unless includeInactive.\n\n**Operation id:** `stations_list` — the same operation is `app.stations.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pack", "receive", "qc", "count", "ship", "production" ] } }, { "name": "includeInactive", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "stations_create", "summary": "stations_create", "description": "Create a station in a warehouse. kind is pack/receive/qc/count/ship/production; the code is uppercased and must be unique in the warehouse; name defaults to the code. The optional travel coordinates x/y/z are the routing depot — a pack station's coords feed the pick tour's end, a receiving station's feed putaway's start.\n\n**Operation id:** `stations_create` — the same operation is `app.stations.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "kind": { "type": "string", "enum": [ "pack", "receive", "qc", "count", "ship", "production" ] }, "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" }, "active": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "warehouseId", "kind", "code" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations/assemblified-workstation": { "post": { "operationId": "stations_set_assemblified_workstation", "summary": "stations_set_assemblified_workstation", "description": "Map an active production station to an explicit Assemblified workstation ID. One mapping per warehouse, with compare-and-set protection.\n\n**Operation id:** `stations_set_assemblified_workstation` — the same operation is `app.stations.set_assemblified_workstation({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_set_assemblified_workstation`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "workstationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "expectedWorkstationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] } }, "required": [ "stationId", "workstationId", "expectedWorkstationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations/delete": { "post": { "operationId": "stations_delete", "summary": "stations_delete", "description": "Delete a station. Every reference is cleared first (bounded): zones defaulting to it, worker profiles homed at it, tasks pinned to it, a receipt's receiving station and a pick batch's destination station — an in-flight batch's final leg then resolves as unplaced. The station's timeline records how many of each were cleared. Pack history keeps its parcels, photos and packing details with the station cleared, and the station's device health is removed with it.\n\n**Operation id:** `stations_delete` — the same operation is `app.stations.delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "stationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations/devices": { "get": { "operationId": "stations_devices_list", "summary": "stations_devices_list", "description": "List the active pack stations (max 200) with their device profile (printer, scale, camera; null = every step is manual), the health each device slot last reported (ready/problem/unknown, when, the floor device that reported it) and the printer's cached PrintNode state. Filter by warehouse. No pack figures per station.\n\n**Operation id:** `stations_devices_list` — the same operation is `app.stations.devices_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_devices_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "stations_set_devices", "summary": "stations_set_devices", "description": "Replace a pack station's device profile: printer (a PrintNode printer discovered under Carriers & packaging), scale (a USB scale read in the pack PC's browser, or a discovered PrintNode scale), camera (the device's own). null clears it. Only pack stations; pass the devicesRevision you read — a newer one is refused (conflict, revision_mismatch).\n\n**Operation id:** `stations_set_devices` — the same operation is `app.stations.set_devices({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_set_devices`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stationId": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "devices": { "anyOf": [ { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "printer": { "anyOf": [ { "type": "object", "properties": { "driver": { "type": "string", "const": "printnode" }, "providerPrinterId": { "type": "string", "minLength": 1, "maxLength": 64, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "computerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "driver", "providerPrinterId", "computerId", "label" ] }, { "type": "null" } ] }, "scale": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "driver": { "type": "string", "const": "browser_hid" } }, "required": [ "driver" ] }, { "type": "object", "properties": { "driver": { "type": "string", "const": "printnode" }, "computerId": { "type": "string", "minLength": 1, "maxLength": 64, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "deviceName": { "type": "string", "minLength": 1, "maxLength": 120 }, "deviceNum": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "driver", "computerId", "deviceName", "deviceNum", "label" ] } ] }, { "type": "null" } ] }, "camera": { "anyOf": [ { "type": "object", "properties": { "driver": { "type": "string", "const": "browser" } }, "required": [ "driver" ] }, { "type": "null" } ] }, "scaleTestedAtMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "v", "printer", "scale", "camera", "scaleTestedAtMs" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The station's devicesRevision the form was read at; a newer one is refused." } }, "required": [ "stationId", "devices", "revision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations/get": { "get": { "operationId": "stations_get", "summary": "stations_get", "description": "Get one station by document id, or null when unknown.\n\n**Operation id:** `stations_get` — the same operation is `app.stations.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "query", "parameters": [ { "name": "stationId", "in": "query", "required": true, "description": "document id of the station.", "schema": { "type": "string", "description": "document id of the station.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stations/update": { "post": { "operationId": "stations_update", "summary": "stations_update", "description": "Update a station: kind, code (re-uppercased, must stay unique), name, the travel coordinates x/y/z (null clears a coordinate) and the active flag. Only the fields you pass change.\n\n**Operation id:** `stations_update` — the same operation is `app.stations.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stations_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stations" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stationId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "kind": { "type": "string", "enum": [ "pack", "receive", "qc", "count", "ship", "production" ] }, "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "z": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "stationId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores": { "get": { "operationId": "stores_list", "summary": "stores_list", "description": "The account's Shopify stores, home first: each store's id (the store reference lists and filters use — never its domain), its name, its badge colour index, its state (live, or leaving once it uninstalled) and whether it is the home store. One row for an account with one store.\n\n**Operation id:** `stores_list` — the same operation is `app.stores.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/overview": { "get": { "operationId": "stores_overview", "summary": "stores_overview", "description": "Settings › Stores: every store of the account, home first, with what its row says — its state (live or leaving), whether Floormode updates its stock numbers yet (`started`; the home store always), when it joined and who joined it (`joinedBy`: the name the join recorded, their person once they opened Floormode through it, and whether that person still needs a role), its own plan, and — once the account has two stores — whether its stock numbers drift from Floormode's at any warehouse (`drift`; they are compared every night). `connectBlock` names why another store cannot be connected now (ten stores, or a store still leaving). Needs stores.manage.\n\n**Operation id:** `stores_overview` — the same operation is `app.stores.overview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_overview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}": { "get": { "operationId": "stores_get", "summary": "stores_get", "description": "One store's page: the same facts as its `stores_overview` row, plus the main store's name and the account's plan, which sets every store's features and order allowance (a joined store's own plan only releases its new orders), what its open orders do if it leaves (`onLeave`: hold their stock for 14 days, or put it back at once) and, once it left, `leaving`: when it left, when its hold ends, the whole days left until then and how many orders still hold stock (counted up to five hundred, `heldCapped`). Needs stores.manage.\n\n**Operation id:** `stores_get` — the same operation is `app.stores.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}/drift/{warehouseId}": { "get": { "operationId": "stores_drift_get", "summary": "stores_drift_get", "description": "A store's stock-number drift at one warehouse (multi-store): the open episode — how many items its Shopify shows differently from Floormode, up to three examples (the item, Shopify's number and Floormode's), every drifted product id (two hundred at most) and whether more drifted — and the warehouse's bins that hold those items, which a count (`counts_create`) covers. `episode` is null while none is open, and always for an account with one store. Needs stores.manage.\n\n**Operation id:** `stores_drift_get` — the same operation is `app.stores.drift_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_drift_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "warehouseId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}/held-orders": { "get": { "operationId": "stores_held_orders", "summary": "stores_held_orders", "description": "A store that left the account (multi-store): its open orders that still hold stock for their customer, 25 a page — each with its name, when it was placed, the units its reservations hold and where they are (`packed` with its pack job, `picking`, or `shelf`). They stay workable until the hold ends. Empty for a store that is still connected. Needs stores.manage.\n\n**Operation id:** `stores_held_orders` — the same operation is `app.stores.held_orders({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_held_orders`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}/link-suggestions": { "get": { "operationId": "item_links_suggestions", "summary": "item_links_suggestions", "description": "Product links (multi-store): what the matcher made of a joined store's unlinked products, one class a page at a time — matched (one product of another store answers to its SKU or barcode), check (a candidate to decide on, with the reason) or unmatched — each with the product it would link to, and the exact count of every class. Needs stores.manage.\n\n**Operation id:** `item_links_suggestions` — the same operation is `app.item.links_suggestions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/item_links_suggestions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "class", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "matched", "check", "unmatched" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}/links": { "get": { "operationId": "item_links_list", "summary": "item_links_list", "description": "Product links (multi-store): a store's linked products, newest first — each with the product of another store that holds its stock, when it was linked and who linked it (null when Floormode linked an exact new match). `source: auto` lists Floormode's links alone. Needs stores.manage.\n\n**Operation id:** `item_links_list` — the same operation is `app.item.links_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/item_links_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "source", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "auto", "all" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/stores/{storeId}/start-preview": { "get": { "operationId": "stores_start_preview", "summary": "stores_start_preview", "description": "A joined store's start preview (multi-store): what pressing Start would write to its Shopify — how many of its products' numbers stay, go down, go up and go to 0, how many are left alone, the up to one hundred biggest changes (those going to 0 first, each with its warehouse, the store's number now and after), whether the preview still holds (`fresh`: no link, bring-in or location changed since), the products brought in on their own stock, and the stock update running now. Needs stores.manage.\n\n**Operation id:** `stores_start_preview` — the same operation is `app.stores.start_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/stores_start_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "stores" ], "x-operation-kind": "query", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string", "description": "A channelInstallations id, e.g. \"channelInstallations_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/catch-up": { "post": { "operationId": "sync_catchUpNow", "summary": "sync_catchUpNow", "description": "Catch up with Shopify now: re-read the orders, products, stock and native transfers that changed since the last nightly catch-up, for every store of the account, and apply what moved. It runs in the background a moment after the call; requests within five minutes are one catch-up. Floormode also catches up every night by itself.\n\n**Operation id:** `sync_catchUpNow` — the same operation is `app.sync.catchUpNow({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sync_catchUpNow`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "mutation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/ingest/dead": { "get": { "operationId": "ingest_dead_list", "summary": "ingest_dead_list", "description": "Dead-lettered inbound deliveries, newest first: topic, resource, dedupe key, last error and whether a stored apply plan makes the row replayable. A disclosed page (`rows`/`capped`/`cursor`): pass the answered `cursor` for the next page (`before` = the last row's createdAt is the legacy continuation).\n\n**Operation id:** `ingest_dead_list` — the same operation is `app.ingest.dead_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/ingest_dead_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "query", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows per page (max 50).", "schema": { "default": 50, "description": "Rows per page (max 50).", "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Return rows created strictly before this epoch-ms stamp (legacy cursor).", "schema": { "description": "Return rows created strictly before this epoch-ms stamp (legacy cursor).", "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` the previous page answered with (keyset continuation).", "schema": { "description": "The `cursor` the previous page answered with (keyset continuation).", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/ingest/health": { "get": { "operationId": "ingest_health", "summary": "ingest_health", "description": "Inbound sync health (the ingest spine): exact counters per staged-delivery status (queued, processing, retrying, dead, applied/ignored in the last 24h), the oldest still-open delivery, the newest applied one and how many of the receipts the spine itself opened (source shopify_webhook, backfill_page or opening_page — never the carrier-tracking door's) failed in the last 24h. What the Settings → Integrations inbound tiles render. Also returns the 25 oldest unresolved inventory-relevant receipts across all time, with exact delivery references and staged-queue linkage; capped is explicit. These use the same predicate that blocks inventory verification.\n\n**Operation id:** `ingest_health` — the same operation is `app.ingest.health({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/ingest_health`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/ingest/recover-source": { "post": { "operationId": "ingest_recoverSource", "summary": "ingest_recoverSource", "description": "Audited authoritative refetch of a bodyless dead Shopify reverse-fulfillment disposition or fulfillment-order hold delivery, including a failed Shopify receipt with no staged row. Select exactly one ingestId or failedReceiptId. Requires its verified resource GID and delivery evidence. Retains the original failure and dedupe key; only the ingest drain records the eventual apply outcome.\n\n**Operation id:** `ingest_recoverSource` — the same operation is `app.ingest.recoverSource({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/ingest_recoverSource`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ingestId": { "type": "string", "description": "A ingestQueue id, e.g. \"ingestQueue_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "failedReceiptId": { "type": "string", "description": "A webhookEvents id, e.g. \"webhookEvents_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "resourceId": { "type": "string", "maxLength": 100, "pattern": "^gid:\\/\\/shopify\\/(?:ReverseFulfillmentOrder|FulfillmentOrder)\\/[1-9]\\d*$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "evidenceReference": { "type": "string", "minLength": 8, "maxLength": 200 }, "verifiedSource": { "type": "boolean", "const": true } }, "required": [ "resourceId", "evidenceReference", "verifiedSource" ], "oneOf": [ { "required": [ "ingestId" ] }, { "required": [ "failedReceiptId" ] } ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/ingest/replay": { "post": { "operationId": "ingest_replay", "summary": "ingest_replay", "description": "Manually redrive one dead inbound delivery: resets the row to queued with a fresh attempt budget and arms the drain. Refuses rows without a stored apply plan (those heal via Shopify's redelivery of the same webhook) and rows that are not dead.\n\n**Operation id:** `ingest_replay` — the same operation is `app.ingest.replay({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/ingest_replay`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ingestId": { "type": "string", "description": "document id of the dead ingest row.", "format": "floormode-id" } }, "required": [ "ingestId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/jobs/get": { "get": { "operationId": "sync_job_get", "summary": "sync_job_get", "description": "One sync job by id — the row POST /api/sync/backfill returns the id of. Status (running, done, failed), current phase/page and the applied counts; success is only ever this row saying done, never the accepted response that started the job. Returns null for an unknown id.\n\n**Operation id:** `sync_job_get` — the same operation is `app.sync.job_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sync_job_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "query", "parameters": [ { "name": "jobId", "in": "query", "required": true, "description": "document id of the sync job.", "schema": { "type": "string", "description": "document id of the sync job.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/jobs/latest": { "get": { "operationId": "sync_jobs_latest", "summary": "sync_jobs_latest", "description": "Progress of the newest sync job — the install backfill (PLT-002) or an opening-stock import: status (running, done, failed), the phase currently running and the applied counts. Returns null when the shop never ran one.\n\n**Operation id:** `sync_jobs_latest` — the same operation is `app.sync.jobs_latest({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sync_jobs_latest`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "query", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Job kind; defaults to backfill.", "schema": { "description": "Job kind; defaults to backfill.", "type": "string", "enum": [ "backfill", "opening_import", "store_publication" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/sync/last-night": { "get": { "operationId": "sync_last_night", "summary": "sync_last_night", "description": "What the newest completed nightly catch-up brought up to date, summed over the account's stores: orders, fulfillments, stock levels and products Shopify had changed that Floormode did not hold yet, waiting updates it sent, and the checks Shopify refused or that did not finish. `night` is null when no night ran in the last week (a night runs only after a day with changes); `running` while tonight's catch-up is under way.\n\n**Operation id:** `sync_last_night` — the same operation is `app.sync.last_night({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/sync_last_night`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "sync" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks": { "get": { "operationId": "tasks_list", "summary": "tasks_list", "description": "List tasks a page at a time (`rows`/`capped`/`cursor`, max 100), oldest first (`created:asc`, the default) or newest first. Scope: EXACTLY ONE of `warehouseId`, `zoneId` (the zone's own tasks), `stationId` (the station's warehouse) or `assignedTo` (a worker's plate); none or two are refused. Filters are server predicates: `types` and `statuses` as sets (open = pending, claimed, assigned, inProgress; pending unassigned tasks are the claimable pool), `assignment` (`mine` = the caller's own, `unassigned` = nobody's), `floorOnly` (no pick task minted on an allocation), `returnToShelfOnly`. `openCount` is the scope's exact number of open tasks on every page. Breaking since 2026-10-07: the single-valued `type` / `status` and `openOnly` are refused; pass the sets.\n\n**Operation id:** `tasks_list` — the same operation is `app.tasks.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Only this warehouse's tasks.", "schema": { "description": "Only this warehouse's tasks.", "type": "string", "format": "floormode-id" } }, { "name": "zoneId", "in": "query", "required": false, "description": "Only this zone's tasks; implies the zone's warehouse.", "schema": { "description": "Only this zone's tasks; implies the zone's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "stationId", "in": "query", "required": false, "description": "Narrows to the station's warehouse.", "schema": { "description": "Narrows to the station's warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "assignedTo", "in": "query", "required": false, "description": "One worker's plate (their user id); the one scope that needs no warehouse.", "schema": { "description": "One worker's plate (their user id); the one scope that needs no warehouse.", "type": "string", "minLength": 1 } }, { "name": "types", "in": "query", "required": false, "description": "Any of these task types; absent = every type. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these task types; absent = every type.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } } }, { "name": "statuses", "in": "query", "required": false, "description": "Any of these statuses; absent = every status. The open set is pending, claimed, assigned, inProgress. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these statuses; absent = every status. The open set is pending, claimed, assigned, inProgress.", "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "pending", "claimed", "assigned", "inProgress", "done", "cancelled" ] } } }, { "name": "assignment", "in": "query", "required": false, "description": "`mine` = the caller's own tasks; `unassigned` = nobody's (the claimable pool).", "schema": { "description": "`mine` = the caller's own tasks; `unassigned` = nobody's (the claimable pool).", "type": "string", "enum": [ "mine", "unassigned" ] } }, { "name": "floorOnly", "in": "query", "required": false, "description": "Leave out the pick tasks that belong to the pick queue. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Leave out the pick tasks that belong to the pick queue.", "type": "boolean" } }, { "name": "returnToShelfOnly", "in": "query", "required": false, "description": "Only cancelled-pick goods waiting for physical return to a bin. Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only cancelled-pick goods waiting for physical return to a bin.", "type": "boolean" } }, { "name": "binMovesOnly", "in": "query", "required": false, "description": "Only tasks that move goods out of a named bin of the warehouse (put away, refill, move, return to shelf). Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "description": "Only tasks that move goods out of a named bin of the warehouse (put away, refill, move, return to shelf).", "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "`created:asc` (oldest first, the default) or `created:desc`.", "schema": { "description": "`created:asc` (oldest first, the default) or `created:desc`.", "type": "string", "enum": [ "created:asc", "created:desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Tasks per page (max 100).", "schema": { "description": "Tasks per page (max 100).", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/auto-assign-pick": { "post": { "operationId": "tasks_auto_assign_pick", "summary": "tasks_auto_assign_pick", "description": "Auto order→picker assignment (WHT-013): create the pick task for a pickable fulfillment order and push it to the least-loaded eligible worker (least_loaded default, or round_robin), or leave it in the pool when nobody is eligible. Idempotent — a live task for the same allocation is returned instead of a duplicate. Returns null when the FO is not pickable (not fully allocated / held / already in pick work).\n\n**Operation id:** `tasks_auto_assign_pick` — the same operation is `app.tasks.auto_assign_pick({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_auto_assign_pick`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "foDocId": { "type": "string", "description": "document id of the fulfillment order.", "format": "floormode-id" }, "strategy": { "description": "Defaults to least_loaded.", "type": "string", "enum": [ "least_loaded", "round_robin" ] } }, "required": [ "foDocId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/cancel": { "post": { "operationId": "tasks_cancel", "summary": "tasks_cancel", "description": "Cancel a task (overlay closed without doing the work). Rejected once terminal.\n\n**Operation id:** `tasks_cancel` — the same operation is `app.tasks.cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "reason": { "type": "string" } }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/claim": { "post": { "operationId": "tasks_claim", "summary": "tasks_claim", "description": "A worker pulls the top eligible pending task from a warehouse's claimable pool (assignedTo null + status pending), scoped by the caller's worker profile (assigned zones + canDo + skills), ordered by priority then FIFO. Optionally restrict to one task type. Returns the claimed task, or null when nothing is eligible.\n\n**Operation id:** `tasks_claim` — the same operation is `app.tasks.claim({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_claim`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "type": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/complete": { "post": { "operationId": "tasks_complete", "summary": "tasks_complete", "description": "Complete a task: records completedAt and actualDuration (completedAt − startedAt, null when never started) for productivity. Returns the actualDuration.\n\n**Operation id:** `tasks_complete` — the same operation is `app.tasks.complete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_complete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/get": { "get": { "operationId": "tasks_get", "summary": "tasks_get", "description": "Get one task by document id, or null when unknown.\n\n**Operation id:** `tasks_get` — the same operation is `app.tasks.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "document id of the task.", "schema": { "type": "string", "description": "document id of the task.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/move": { "get": { "operationId": "tasks_move_get", "summary": "tasks_move_get", "description": "Get a put-away, refill or move task as Floor Mode works it (take from → bring to): the source bin, the item, the lot it names (or the source's lots when it holds only lotted units), the planned destination, units planned, moved and left, unreserved units at the source, and the task's own movements. A return to shelf answers `{ variant: \"return\" }` (read it with tasks_return_to_shelf_get). Null for an unknown task or one with no bin move.\n\n**Operation id:** `tasks_move_get` — the same operation is `app.tasks.move_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_move_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "tasks_move", "summary": "tasks_move", "description": "Move a put-away, refill or move task's goods from its source bin to a scanned shelf bin, in one stock movement. Requires the source, item and destination scans (and the lot where the task names one or the source holds only lotted units). Send either `scannedCode` or `variantId` (an item no code finds, named). A destination other than the task's planned bin is refused (`not_planned_bin`) unless `retarget` is true, and must be a sellable shelf bin. Partial moves leave the rest on the task; the task completes when every unit moved. Idempotency keys bind source, destination, item, lot and quantity. Never takes another order's reserved units. A return to shelf uses tasks_return_to_shelf.\n\n**Operation id:** `tasks_move` — the same operation is `app.tasks.move({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_move`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedFromBin": { "type": "string", "minLength": 1 }, "scannedCode": { "description": "Item barcode or sku.", "type": "string", "minLength": 1 }, "variantId": { "description": "The item named instead of scanned (one with no usable code).", "type": "string", "format": "floormode-id" }, "scannedLotNumber": { "type": "string" }, "scannedToBin": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "method": { "description": "How the item was confirmed (scan, camera, typed, tap; desk for a desk caller). Omitted: scan with a code, tap without, desk for a desk caller. paper is refused.", "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "description": "A lead's single-use grant for a tap where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" }, "retarget": { "description": "Move to the scanned bin although the task planned another.", "type": "boolean" } }, "required": [ "taskId", "scannedFromBin", "scannedToBin", "qty", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/move/scan": { "get": { "operationId": "tasks_move_scan", "summary": "tasks_move_scan", "description": "Resolve a source, item or destination label in a move task's warehouse. Recognizes the task's item even after catalog deletion; unrelated deleted items stay excluded.\n\n**Operation id:** `tasks_move_scan` — the same operation is `app.tasks.move_scan({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_move_scan`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/move/source-empty": { "post": { "operationId": "tasks_move_source_empty", "summary": "tasks_move_source_empty", "description": "A lead's \"Source bin is empty\" on a refill or move task: the goods are not in the task's source bin. The bin is flagged as a problem (it then needs a count) and the task closes — done when some units already moved, cancelled when none did. A put-away off the receiving dock and a return to shelf are refused.\n\n**Operation id:** `tasks_move_source_empty` — the same operation is `app.tasks.move_source_empty({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_move_source_empty`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "note": { "type": "string", "maxLength": 200 } }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/move/suggest": { "get": { "operationId": "tasks_move_suggest", "summary": "tasks_move_suggest", "description": "The bin the warehouse's putaway strategy proposes for a move task's goods (never its source bin): `seed` is the booking key the caller will send, so a spread warehouse proposes the same bin for a retry; `excludeBinIds` skips bins the stock door refused.\n\n**Operation id:** `tasks_move_suggest` — the same operation is `app.tasks.move_suggest({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_move_suggest`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "seed", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "excludeBinIds", "in": "query", "required": false, "description": "Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "maxItems": 10, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/return-to-shelf": { "get": { "operationId": "tasks_return_to_shelf_get", "summary": "tasks_return_to_shelf_get", "description": "Get a cancelled pick's physical return task, source bin, item, lot, remaining and unreserved quantities, and bounded putaway history. Null for unknown or non-return tasks. Goods stay in packing until the worker confirms a move.\n\n**Operation id:** `tasks_return_to_shelf_get` — the same operation is `app.tasks.return_to_shelf_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_return_to_shelf_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "tasks_return_to_shelf", "summary": "tasks_return_to_shelf", "description": "Confirm a physical return of cancelled-picked goods from packing to a scanned active sellable shelf bin. Requires source, item, destination and tracked-lot scans. Send either `scannedCode` or `variantId`: an item with no usable code (none of its barcode, alias barcodes or SKU resolves to it for this task) is named by its variant and must be the task's item, exactly as a scan of it; an item with a usable code is refused when named (send its code). Supports partial returns; task completes only when all units moved. Idempotency keys bind destination, item, lot and quantity. Never consumes another order's reserved stock. Generic task Complete and Cancel cannot discard this obligation.\n\n**Operation id:** `tasks_return_to_shelf` — the same operation is `app.tasks.return_to_shelf({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_return_to_shelf`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "scannedFromBin": { "type": "string", "minLength": 1 }, "scannedCode": { "description": "Item barcode or sku.", "type": "string", "minLength": 1 }, "variantId": { "description": "The item named instead of scanned (one with no usable code).", "type": "string", "format": "floormode-id" }, "scannedLotNumber": { "type": "string" }, "scannedToBin": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "method": { "description": "How the item was confirmed (scan, camera, typed, tap; desk for a desk caller). Omitted: scan with a code, tap without, desk for a desk caller. paper is refused.", "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "description": "A lead's single-use grant for a tap where the warehouse confirms by scan only.", "type": "string", "format": "floormode-id" } }, "required": [ "taskId", "scannedFromBin", "scannedToBin", "qty", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/return-to-shelf/scan": { "get": { "operationId": "tasks_return_to_shelf_scan", "summary": "tasks_return_to_shelf_scan", "description": "Resolve a source, item or destination label in a physical return task's warehouse. Recognizes its known stock item even after catalog deletion; unrelated deleted items stay excluded.\n\n**Operation id:** `tasks_return_to_shelf_scan` — the same operation is `app.tasks.return_to_shelf_scan({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_return_to_shelf_scan`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "query", "parameters": [ { "name": "taskId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tasks/start": { "post": { "operationId": "tasks_start", "summary": "tasks_start", "description": "Mark a task in progress (stamps startedAt once). Rejected once done/cancelled.\n\n**Operation id:** `tasks_start` — the same operation is `app.tasks.start({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tasks_start`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tasks" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tenant": { "get": { "operationId": "tenant_current", "summary": "tenant_current", "description": "Return the authenticated tenant identity (id, source, actor).\n\n**Operation id:** `tenant_current` — the same operation is `app.tenant.current({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/tenant_current`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tenant" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/trackers/get": { "get": { "operationId": "trackers_get", "summary": "trackers_get", "description": "Get the canonical tracker of one shipment: current status + statusDetail and the bounded checkpoint history. Returns null before the first tracking event.\n\n**Operation id:** `trackers_get` — the same operation is `app.trackers.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/trackers_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "trackers" ], "x-operation-kind": "query", "parameters": [ { "name": "shipmentId", "in": "query", "required": true, "description": "document id of the shipment.", "schema": { "type": "string", "description": "document id of the shipment.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/tracking-brand/logo": { "get": { "operationId": "trackingBrand_logo_get", "summary": "trackingBrand_logo_get", "description": "Read the managed tracking logo's revision and dimensions without image bytes.\n\n**Operation id:** `trackingBrand_logo_get` — the same operation is `app.trackingBrand.logo_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/trackingBrand_logo_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "tracking-brand" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/user-prefs": { "get": { "operationId": "user_prefs_list", "summary": "user_prefs_list", "description": "List the calling user's preferences as a page (max 100; `capped` says more exist).\n\n**Operation id:** `user_prefs_list` — the same operation is `app.user.prefs_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/user_prefs_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "user-prefs" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "user_prefs_set", "summary": "user_prefs_set", "description": "Set one preference of the calling user; the value must be valid JSON.\n\n**Operation id:** `user_prefs_set` — the same operation is `app.user.prefs_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/user_prefs_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "user-prefs" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "valueJson": { "type": "string", "maxLength": 4000, "description": "A JSON document, at most 4000 characters." } }, "required": [ "key", "valueJson" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/user-prefs/batch": { "post": { "operationId": "user_prefs_set_many", "summary": "user_prefs_set_many", "description": "Set up to 10 preferences of the calling user in ONE transaction (each value must be valid JSON, each key at most once); answers every row as stored.\n\n**Operation id:** `user_prefs_set_many` — the same operation is `app.user.prefs_set_many({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/user_prefs_set_many`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "user-prefs" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "valueJson": { "type": "string", "maxLength": 4000 } }, "required": [ "key", "valueJson" ] } } }, "required": [ "entries" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/user-prefs/get": { "get": { "operationId": "user_prefs_get", "summary": "user_prefs_get", "description": "Read one preference of the calling user as a JSON string, or null. The user comes from the token — preferences of other users are not reachable.\n\n**Operation id:** `user_prefs_get` — the same operation is `app.user.prefs_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/user_prefs_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "user-prefs" ], "x-operation-kind": "query", "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/values/suggest": { "get": { "operationId": "values_suggest", "summary": "values_suggest", "description": "Known values for a field, to suggest instead of guessing: `order_tag` = the tags on the newest 1000 orders, most recently used first; `product_type` = the types of the first 1000 live products by title, alphabetical; `order_priority` = the priorities the automation rules set, then those on the newest 1000 orders; `sku` = live items' SKUs in SKU order from `prefix`, 200 items at most. Up to 50 distinct values (case-insensitive), narrowed by `prefix`; `capped` = more may exist beyond the page or the window. Who reads a facet: `order_tag` orders.view or automation.manage; `product_type` inventory.view or automation.manage; `order_priority` orders.view or automation.manage or settings.manage or fulfillment.plan; `sku` inventory.view or automation.manage or settings.manage or fulfillment.plan. Derived on every read, never stored.\n\n**Operation id:** `values_suggest` — the same operation is `app.values.suggest({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/values_suggest`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "values" ], "x-operation-kind": "query", "parameters": [ { "name": "facet", "in": "query", "required": true, "description": "`order_tag`: tags on the newest orders. `product_type`: live products' types. `order_priority`: the priorities automation rules set, deleted rules' included. `sku`: live items' SKUs.", "schema": { "type": "string", "enum": [ "order_tag", "product_type", "order_priority", "sku" ], "description": "`order_tag`: tags on the newest orders. `product_type`: live products' types. `order_priority`: the priorities automation rules set, deleted rules' included. `sku`: live items' SKUs." } }, { "name": "prefix", "in": "query", "required": false, "description": "Only values starting with this text, compared the way rules compare tags.", "schema": { "description": "Only values starting with this text, compared the way rules compare tags.", "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/barcode-aliases": { "get": { "operationId": "variants_barcode_aliases", "summary": "variants_barcode_aliases", "description": "Read exact supplemental scan identifiers with channel/merchant/peer ownership, primary barcode and revision. Merchant aliases are locally managed and never overwrite source catalog data.\n\n**Operation id:** `variants_barcode_aliases` — the same operation is `app.variants.barcode_aliases({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_barcode_aliases`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "variants_set_barcode_aliases", "summary": "variants_set_barcode_aliases", "description": "Replace up to 50 merchant-owned barcode aliases with compare-and-set protection. Refuses duplicate identifiers or collisions with another active item/location. Source-owned aliases and the primary barcode remain under their source's ownership.\n\n**Operation id:** `variants_set_barcode_aliases` — the same operation is `app.variants.set_barcode_aliases({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_set_barcode_aliases`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "aliases": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "expectedRevision": { "type": "string", "minLength": 1 } }, "required": [ "variantId", "aliases", "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/by-ids": { "post": { "operationId": "variants_by_ids", "summary": "variants_by_ids", "description": "Resolve up to 200 variants by document id to their label data (sku, barcode, variant title, product title). Unknown or foreign ids are skipped. Deleted variants remain available for historical labels unless liveOnly is true.\n\n**Operation id:** `variants_by_ids` — the same operation is `app.variants.by_ids({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_by_ids`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "document ids of the variants." }, "liveOnly": { "description": "Exclude deleted variants for operational selection.", "type": "boolean" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/confirm-mode": { "get": { "operationId": "variants_get_confirm_mode", "summary": "variants_get_confirm_mode", "description": "Read how Floor Mode may confirm one item: confirmMode (default or no_scan), hasCode (it has a barcode, a SKU or an alias a scan finds) and liveVariants (its product's live variants). Null for an unknown or deleted item.\n\n**Operation id:** `variants_get_confirm_mode` — the same operation is `app.variants.get_confirm_mode({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_get_confirm_mode`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "variants_set_confirm_mode", "summary": "variants_set_confirm_mode", "description": "Sets how Floor Mode may confirm items: no_scan lets the item step be confirmed by eye (a tap) under every warehouse setting, for items without a barcode or checked by eye — the bin is still scanned; default follows the warehouse. Target every live variant of a product (`{productId}`) or up to 200 items (`{variantIds}`). Kept through product syncs. Answers how many items changed.\n\n**Operation id:** `variants_set_confirm_mode` — the same operation is `app.variants.set_confirm_mode({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_set_confirm_mode`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "object", "properties": { "productId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "productId" ], "additionalProperties": false }, { "type": "object", "properties": { "variantIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } }, "required": [ "variantIds" ], "additionalProperties": false } ] }, "confirmMode": { "type": "string", "enum": [ "default", "no_scan" ] } }, "required": [ "target", "confirmMode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/confirm-mode/import": { "post": { "operationId": "variants_import_confirm_mode", "summary": "variants_import_confirm_mode", "description": "Imports the Scanning column: one row per SKU with confirmMode no_scan (the floor may confirm the item by eye, without a scan; the bin is still scanned) or default (as the warehouse says), at most 500 rows per call. Each SKU must name one live item: a row naming none or several is reported in skipped (unknown_sku, ambiguous_sku) and changes nothing. Later rows win for the same item. Answers how many items changed and how many were already in their mode. Bound to requestKey: the same rows under the same key answer the first result again (replayed: true) and write nothing.\n\n**Operation id:** `variants_import_confirm_mode` — the same operation is `app.variants.import_confirm_mode({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_import_confirm_mode`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "rows": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1 }, "confirmMode": { "type": "string", "enum": [ "default", "no_scan" ], "description": "\"no_scan\": the floor may confirm the item by eye, without a scan; \"default\": as the warehouse says." } }, "required": [ "sku", "confirmMode" ] } } }, "required": [ "requestKey", "rows" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/customs": { "get": { "operationId": "variants_get_customs", "summary": "variants_get_customs", "description": "Read the customs facts Shopify holds for one variant (B5): hsCode (base HS code), originCountry (ISO alpha-2), countryCodes (one { country, code } per country that issued a tariff number, at most 25; complete false when Shopify holds more), syncedAtMs (when Floormode last read the codes, null before the first read) and adminUrl (the variant in Shopify admin, the one place to edit them). Read-only. Returns null for an unknown, deleted or local item.\n\n**Operation id:** `variants_get_customs` — the same operation is `app.variants.get_customs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_get_customs`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/dangerous-goods": { "post": { "operationId": "variants_bulk_set_dangerous_goods", "summary": "variants_bulk_set_dangerous_goods", "description": "Mark up to 200 items as one dangerous-goods class (roadmap B4): `dangerousGoods` (none, lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated) and its `unNumber` (a lithium class takes UN3481 / UN3480 when omitted; a limited quantity or a fully regulated class needs one: refused `un_number_invalid`). A linked listing marks the stock item it sells. Restricts shipping: a marked item's orders get labels only from carriers that carry its class. Kept through product syncs. Answers how many items changed, how many already held it, and the ids that name no live item (`unknown_item`). Pass a `requestKey` to make a retry answer the first result.\n\n**Operation id:** `variants_bulk_set_dangerous_goods` — the same operation is `app.variants.bulk_set_dangerous_goods({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_bulk_set_dangerous_goods`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "dangerousGoods": { "type": "string", "enum": [ "none", "lithium_in_equipment", "lithium_with_equipment", "lithium_alone", "limited_quantity", "regulated" ] }, "unNumber": { "description": "Four digits (UN3481 or 3481). A lithium class takes UN3481 / UN3480 when omitted and only its own numbers; a limited quantity or a fully regulated class needs one.", "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "variantIds", "dangerousGoods" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/dimensions": { "get": { "operationId": "variants_get_dimensions", "summary": "variants_get_dimensions", "description": "Read the volumetric dimensions and the handling of one variant (length/width/height in mm, weight in g, units per carton, stackable, oversized, its dangerous-goods class and UN number). Null fields are unset. Returns null for an unknown variant.\n\n**Operation id:** `variants_get_dimensions` — the same operation is `app.variants.get_dimensions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_get_dimensions`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "variants_set_dimensions", "summary": "variants_set_dimensions", "description": "Set the volumetric dimensions and the handling of one variant (WHT-004a, roadmap B4): lengthMm, widthMm, heightMm, weightG, unitsPerCarton (whole number), stackable, oversized, and its dangerous goods: `dangerousGoods` (none, lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity, regulated) with its `unNumber` (four digits; a lithium class takes UN3481 / UN3480 when omitted and accepts only its own numbers, a limited quantity or a fully regulated item needs one: refused `un_number_invalid`). A marked item's orders get labels only from carriers that carry its class. Pass null to clear a measure, omit a field to leave it unchanged. Consumed by the capacity engine and the label doors.\n\n**Operation id:** `variants_set_dimensions` — the same operation is `app.variants.set_dimensions({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_set_dimensions`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "lengthMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "widthMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "heightMm": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "weightG": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "unitsPerCarton": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "stackable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "oversized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "dangerousGoods": { "type": "string", "enum": [ "none", "lithium_in_equipment", "lithium_with_equipment", "lithium_alone", "limited_quantity", "regulated" ] }, "unNumber": { "description": "Four digits (UN3481 or 3481). A lithium class takes UN3481 / UN3480 when omitted and only its own numbers; a limited quantity or a fully regulated class needs one.", "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] } }, "required": [ "variantId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/home-bin": { "get": { "operationId": "variants_get_home_bin", "summary": "variants_get_home_bin", "description": "Read the per-SKU fixed home location (WHT-006): {homeBinId, homeBinCode}, both null when the SKU is dynamically slotted. Returns null for an unknown variant.\n\n**Operation id:** `variants_get_home_bin` — the same operation is `app.variants.get_home_bin({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_get_home_bin`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "document id of the variant.", "schema": { "type": "string", "description": "document id of the variant.", "format": "floormode-id" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Narrows to one warehouse; omitted, the first pinned home wins.", "schema": { "description": "Narrows to one warehouse; omitted, the first pinned home wins.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/import-handling": { "post": { "operationId": "variants_import_handling", "summary": "variants_import_handling", "description": "The handling import (roadmap B4): up to 500 rows, each naming an item by `sku` (else `barcode`) with its dangerous-goods class — a key, a label or an alias such as Gefahrgut or LQ — and its `unNumber`. A row that names no item or several, a class outside the vocabulary, a UN number its class refuses, or a second class for an item already in the sheet is reported per row and skipped. Answers how many items changed and how many already held their class. Pass a `requestKey` to make a resent sheet answer the first result.\n\n**Operation id:** `variants_import_handling` — the same operation is `app.variants.import_handling({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_import_handling`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 255 }, "barcode": { "type": "string", "maxLength": 255 }, "dangerousGoods": { "type": "string", "maxLength": 80, "description": "The class: none, lithium_in_equipment, lithium_with_equipment, lithium_alone, limited_quantity or regulated, or its label." }, "unNumber": { "description": "Four digits (UN3481 or 3481). A lithium class takes UN3481 / UN3480 when omitted and only its own numbers; a limited quantity or a fully regulated class needs one.", "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] } }, "required": [ "dangerousGoods" ] } }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "rows" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/search": { "get": { "operationId": "variants_search", "summary": "variants_search", "description": "Search variants by sku, barcode, variant title or product name (max 50 rows); a product found by its name lists each of its live variants. Prefix matches rank before substring matches; an empty query returns the first variants. Backs the variant pickers of the adjust/move dialogs.\n\n**Operation id:** `variants_search` — the same operation is `app.variants.search({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_search`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Sku, barcode, variant title or product name fragment.", "schema": { "description": "Sku, barcode, variant title or product name fragment.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Only variants of active products (order editing).", "schema": { "description": "Only variants of active products (order editing).", "type": "string", "const": "active" } }, { "name": "storeId", "in": "query", "required": false, "description": "Only this store's variants (order editing: the order's `store`).", "schema": { "description": "Only this store's variants (order editing: the order's `store`).", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/tracking": { "get": { "operationId": "variants_get_tracking", "summary": "variants_get_tracking", "description": "Read one item's tracking (roadmap D/E E3a): trackingMode, expiryKind, expiryRequired, serialCapture, trackingChangedAtMs and trackingChangedByName (null while it never changed), and the revision a form binds to. Null for an unknown or deleted item.\n\n**Operation id:** `variants_get_tracking` — the same operation is `app.variants.get_tracking({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_get_tracking`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantId", "in": "query", "required": true, "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "variants_set_tracking", "summary": "variants_set_tracking", "description": "Set what up to 100 items track (roadmap D/E E3a): mode none | lot | serial, and for lots expiryKind (best_before | use_by | expiry | none: the wording of the lot's date) and expiryRequired (a lot without a date is then refused at receipt; forced false when expiryKind is none); for serials serialCapture (pack | receive). An omitted field keeps each item's own value. A lot item asks for its lot at every receipt; an item that tracks none takes no new lot but may still name the lots it holds. Stock already without (or with) a lot is never refused — read variants_tracking_impact first. A serial item with serialCapture pack owes one serial per unit at packing (packing_record_serial); with serialCapture receive, one per unit at receiving (receiving_record_line serials), and packing then accepts only those. A switch away from serial is refused while a unit with a serial is in stock, packed or returned (`details.code: \"serial_units_held\"`); a switch to serialCapture receive while units on hand have no serial unit is refused with how many lack one (`details.code: \"serial_stock_unrecorded\"`, `onHand`, `recorded`). A bundle is refused (`details.code: \"bundle_parent\"`; its components hold the stock), and any refusal refuses the whole call. SIDE EFFECTS: stamps who changed it and when, and records `variant_tracking_changed` on each changed item. Answers {updated, unchanged}.\n\n**Operation id:** `variants_set_tracking` — the same operation is `app.variants.set_tracking({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_set_tracking`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "mode": { "type": "string", "enum": [ "none", "lot", "serial" ] }, "expiryKind": { "type": "string", "enum": [ "best_before", "use_by", "expiry", "none" ] }, "expiryRequired": { "type": "boolean" }, "serialCapture": { "type": "string", "enum": [ "pack", "receive" ] } }, "required": [ "variantIds", "mode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/tracking-impact": { "get": { "operationId": "variants_tracking_impact", "summary": "variants_tracking_impact", "description": "What switching up to 100 items to a tracking mode leaves behind: switching to lot, each item's units on hand without a lot (units: \"without_lot\"); switching away, those with one (\"with_lot\") — the exact sum per item and up to 5 of its bins (binsCapped when it holds more), only for items with such units; alreadyInMode counts the items the switch leaves unchanged. Read-only.\n\n**Operation id:** `variants_tracking_impact` — the same operation is `app.variants.tracking_impact({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_tracking_impact`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "parameters": [ { "name": "variantIds", "in": "query", "required": true, "description": "Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } }, { "name": "mode", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "none", "lot", "serial" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/variants/tracking-in-use": { "get": { "operationId": "variants_tracking_in_use", "summary": "variants_tracking_in_use", "description": "Whether any item tracks lots ({lot}) or serials ({serial}) — what a form that takes a lot before it knows the item (a new receipt's lines) asks. Read-only.\n\n**Operation id:** `variants_tracking_in_use` — the same operation is `app.variants.tracking_in_use({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/variants_tracking_in_use`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "variants" ], "x-operation-kind": "query", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers": { "get": { "operationId": "warehouse_transfers_list", "summary": "warehouse_transfers_list", "description": "List physical warehouse transfers with source, staging, transit and received totals.\n\n**Operation id:** `warehouse_transfers_list` — the same operation is `app.warehouse.transfers_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "direction", "in": "query", "required": false, "description": "With warehouseId: from, to, or either (the default).", "schema": { "description": "With warehouseId: from, to, or either (the default).", "type": "string", "enum": [ "from", "to", "either" ] } }, { "name": "status", "in": "query", "required": false, "description": "Any of these physical statuses; empty or absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these physical statuses; empty or absent = every status.", "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "draft", "ready", "in_progress", "completed", "cancelled" ] } } }, { "name": "channelState", "in": "query", "required": false, "description": "Any of these channel states; empty or absent = every state. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of these channel states; empty or absent = every state.", "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "not_required", "pending", "confirmed", "refused", "ambiguous" ] } } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default), `created:asc` (oldest first), `updated:desc` (recently changed) or `updated:asc` (longest unchanged). A cursor belongs to the sort it was returned under.", "schema": { "description": "`created:desc` (newest first, the default), `created:asc` (oldest first), `updated:desc` (recently changed) or `updated:asc` (longest unchanged). A cursor belongs to the sort it was returned under.", "type": "string", "enum": [ "created:desc", "created:asc", "updated:desc", "updated:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's cursor, under the same sort.", "schema": { "description": "The previous page's cursor, under the same sort.", "type": "string" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "warehouse_transfers_create", "summary": "warehouse_transfers_create", "description": "Create an immutable-adapter physical warehouse transfer draft.\n\n**Operation id:** `warehouse_transfers_create` — the same operation is `app.warehouse.transfers_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requireSourceAvailability": { "type": "boolean" }, "fromWarehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "toWarehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "adapter": { "type": "string", "enum": [ "local", "shopify_native", "logistified" ] }, "lines": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 } }, "required": [ "variantId", "quantity" ] } }, "note": { "type": "string", "maxLength": 2000 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "fromWarehouseId", "toWarehouseId", "adapter", "lines", "idempotencyKey" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/options": { "get": { "operationId": "warehouse_transfers_options", "summary": "warehouse_transfers_options", "description": "Find backend-verified warehouse pairs and item adapter eligibility for transfer drafts.\n\n**Operation id:** `warehouse_transfers_options` — the same operation is `app.warehouse.transfers_options({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_options`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "fromWarehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "toWarehouseId", "in": "query", "required": false, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." }, { "type": "string", "maxLength": 512 } ] } }, { "name": "selectedVariantIds", "in": "query", "required": false, "description": "Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}": { "get": { "operationId": "warehouse_transfers_get", "summary": "warehouse_transfers_get", "description": "Read a transfer with exact bin/lot slices, shipments, receipts and permitted floor actions.\n\n**Operation id:** `warehouse_transfers_get` — the same operation is `app.warehouse.transfers_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/cancel": { "post": { "operationId": "warehouse_transfers_cancel", "summary": "warehouse_transfers_cancel", "description": "Cancel only the unshipped transfer remainder; staged goods must first return to source and transit is preserved.\n\n**Operation id:** `warehouse_transfers_cancel` — the same operation is `app.warehouse.transfers_cancel({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_cancel`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "expectedRevision", "idempotencyKey", "reason" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/destination-options": { "get": { "operationId": "warehouse_transfers_destination_options", "summary": "warehouse_transfers_destination_options", "description": "Read eligible destination leaves for this transfer adapter.\n\n**Operation id:** `warehouse_transfers_destination_options` — the same operation is `app.warehouse.transfers_destination_options({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_destination_options`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/dispatch": { "post": { "operationId": "warehouse_transfers_dispatch", "summary": "warehouse_transfers_dispatch", "description": "Dispatch exact staged slices into immutable shipment transit and create the destination expected receipt.\n\n**Operation id:** `warehouse_transfers_dispatch` — the same operation is `app.warehouse.transfers_dispatch({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_dispatch`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "slices": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "sliceId": { "type": "string", "description": "A warehouseTransferSlices id, e.g. \"warehouseTransferSlices_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 } }, "required": [ "sliceId", "quantity" ] } }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "expectedRevision", "idempotencyKey", "slices" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/edit": { "post": { "operationId": "warehouse_transfers_edit", "summary": "warehouse_transfers_edit", "description": "Edit quantities and note of an unprepared transfer draft with revision protection.\n\n**Operation id:** `warehouse_transfers_edit` — the same operation is `app.warehouse.transfers_edit({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_edit`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "lines": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 } }, "required": [ "variantId", "quantity" ] } }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "expectedRevision" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/external-receipts": { "get": { "operationId": "warehouse_transfers_external_receipts", "summary": "warehouse_transfers_external_receipts", "description": "Read exact external destination arrivals with separate per-receipt provider publication evidence and source lot provenance.\n\n**Operation id:** `warehouse_transfers_external_receipts` — the same operation is `app.warehouse.transfers_external_receipts({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_external_receipts`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "shipmentId", "in": "query", "required": false, "description": "A warehouseTransferShipments id, e.g. \"warehouseTransferShipments_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouseTransferShipments id, e.g. \"warehouseTransferShipments_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "description": "A warehouseTransferExternalReceipts id, e.g. \"warehouseTransferExternalReceipts_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouseTransferExternalReceipts id, e.g. \"warehouseTransferExternalReceipts_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/native-proofs": { "get": { "operationId": "warehouse_transfers_native_proofs", "summary": "warehouse_transfers_native_proofs", "description": "Read retained exact native transfer command acknowledgements, independent of transport retention. These are document ownership proofs, not inventory adjustment groups.\n\n**Operation id:** `warehouse_transfers_native_proofs` — the same operation is `app.warehouse.transfers_native_proofs({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_native_proofs`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "cursor", "in": "query", "required": false, "description": "A warehouseTransferNativeProofs id, e.g. \"warehouseTransferNativeProofs_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouseTransferNativeProofs id, e.g. \"warehouseTransferNativeProofs_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/pick": { "post": { "operationId": "warehouse_transfers_pick", "summary": "warehouse_transfers_pick", "description": "Scan exact item, lot and locations to carry reserved goods into transfer staging. Send either `scannedCode` or `variantId` (an item with no usable code — none of its barcode, alias barcodes or SKU resolves to it in the source warehouse, where this leg scans — named; it must be the line's item, and an item with a usable code there is refused: send its code).\n\n**Operation id:** `warehouse_transfers_pick` — the same operation is `app.warehouse.transfers_pick({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_pick`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "sliceId": { "type": "string", "description": "A warehouseTransferSlices id, e.g. \"warehouseTransferSlices_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "scannedLotNumber": { "type": "string", "maxLength": 256 }, "scannedCode": { "type": "string", "minLength": 1, "maxLength": 256 }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "method": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "type": "string", "description": "A floorApprovals id, e.g. \"floorApprovals_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "scannedSourceBinCode": { "type": "string", "minLength": 1, "maxLength": 256 }, "scannedStagingBinCode": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "expectedRevision", "idempotencyKey", "sliceId", "quantity", "scannedSourceBinCode", "scannedStagingBinCode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/prepare": { "post": { "operationId": "warehouse_transfers_prepare", "summary": "warehouse_transfers_prepare", "description": "Reserve exact source bin and lot slices for the complete transfer demand.\n\n**Operation id:** `warehouse_transfers_prepare` — the same operation is `app.warehouse.transfers_prepare({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_prepare`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "selections": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string", "description": "A warehouseTransferLines id, e.g. \"warehouseTransferLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "fromBinId": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "lotId": { "anyOf": [ { "type": "string", "description": "A lots id, e.g. \"lots_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, { "type": "null" } ] }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "stagingBinId": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "lineId", "fromBinId", "lotId", "quantity" ] } } }, "required": [ "expectedRevision", "idempotencyKey", "selections" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/receive": { "post": { "operationId": "warehouse_transfers_receive", "summary": "warehouse_transfers_receive", "description": "Receive exact shipment units into a scanned destination bin, preserving lot, transit and carried cost. Send either `scannedCode` or `variantId` (an item with no usable code — none of its barcode, alias barcodes or SKU resolves to it in the destination warehouse, where this leg scans — named; it must be the line's item, and an item with a usable code there is refused: send its code).\n\n**Operation id:** `warehouse_transfers_receive` — the same operation is `app.warehouse.transfers_receive({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_receive`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "shipmentLineId": { "type": "string", "description": "A warehouseTransferShipmentLines id, e.g. \"warehouseTransferShipmentLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "toBinId": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "scannedLotNumber": { "type": "string", "maxLength": 256 }, "scannedCode": { "type": "string", "minLength": 1, "maxLength": 256 }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "method": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "type": "string", "description": "A floorApprovals id, e.g. \"floorApprovals_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "scannedDestinationBinCode": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "expectedRevision", "idempotencyKey", "shipmentLineId", "toBinId", "quantity", "scannedDestinationBinCode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/return-to-source": { "post": { "operationId": "warehouse_transfers_return_to_source", "summary": "warehouse_transfers_return_to_source", "description": "Scan staged transfer goods back into their original source location, preserving reservation ownership. Send either `scannedCode` or `variantId` (an item with no usable code — none of its barcode, alias barcodes or SKU resolves to it in the source warehouse, where this leg scans — named; it must be the line's item, and an item with a usable code there is refused: send its code).\n\n**Operation id:** `warehouse_transfers_return_to_source` — the same operation is `app.warehouse.transfers_return_to_source({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_return_to_source`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "mutation", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "sliceId": { "type": "string", "description": "A warehouseTransferSlices id, e.g. \"warehouseTransferSlices_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "scannedLotNumber": { "type": "string", "maxLength": 256 }, "scannedCode": { "type": "string", "minLength": 1, "maxLength": 256 }, "variantId": { "type": "string", "description": "A variants id, e.g. \"variants_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "method": { "type": "string", "enum": [ "scan", "camera", "typed", "tap", "paper", "desk" ] }, "approvalId": { "type": "string", "description": "A floorApprovals id, e.g. \"floorApprovals_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "scannedSourceBinCode": { "type": "string", "minLength": 1, "maxLength": 256 }, "scannedStagingBinCode": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "expectedRevision", "idempotencyKey", "sliceId", "quantity", "scannedSourceBinCode", "scannedStagingBinCode" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouse-transfers/{transferId}/source-options": { "get": { "operationId": "warehouse_transfers_source_options", "summary": "warehouse_transfers_source_options", "description": "Read exact source bin and lot quantities and dedicated transfer staging for one line.\n\n**Operation id:** `warehouse_transfers_source_options` — the same operation is `app.warehouse.transfers_source_options({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouse_transfers_source_options`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouse-transfers" ], "x-operation-kind": "query", "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "description": "A warehouseTransfers id, e.g. \"warehouseTransfers_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "lineId", "in": "query", "required": true, "description": "A warehouseTransferLines id, e.g. \"warehouseTransferLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouseTransferLines id, e.g. \"warehouseTransferLines_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses": { "get": { "operationId": "warehouses_list", "summary": "warehouses_list", "description": "List warehouses with their settings, name-ordered pages of 100; optionally resolve one exact warehouse.\n\n**Operation id:** `warehouses_list` — the same operation is `app.warehouses.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "warehouses_create", "summary": "warehouses_create", "description": "Create a warehouse. Optionally link a mirrored Shopify location and set the stock settings (allowNegative, overReceiptTolerancePct). `inventoryWriter` is NOT settable here: a new warehouse always starts as a non-writer in cutover state `bootstrap`, and only the writer cutover ('Go live') can make it write Shopify availability — a payload carrying the flag is refused.\n\n**Operation id:** `warehouses_create` — the same operation is `app.warehouses.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name of the warehouse." }, "shopifyLocationId": { "description": "Numeric Shopify location id to map, or null.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "active": { "description": "Defaults to true.", "type": "boolean" }, "settings": { "description": "Merged over {allowNegative: false, overReceiptTolerancePct: 0, inventoryWriter: false, writerState: 'bootstrap'}.", "type": "object", "properties": { "allowNegative": { "type": "boolean" }, "overReceiptTolerancePct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Over-receipt tolerance in percent of the expected quantity (0–100)." }, "allowOversell": { "description": "Accept backorders/preorders: a shortfall becomes a backorder (default false).", "type": "boolean" }, "trackLots": { "description": "Retired: replaced by each item's tracking mode (variants_set_tracking). Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "putawayStrategy": { "description": "How new stock is placed: \"together\" (next to the same product, else the emptiest bin; the default) or \"spread\" (prefer bins that do not hold the product yet).", "type": "string", "enum": [ "together", "spread" ] }, "floorConfirm": { "description": "How Floor Mode workers confirm a bin or an item: \"scan\" (a scan or a typed code is required), \"scan_or_tap\" (the default: a device without a scanner may confirm by tapping) or \"tap\" (no scanners: every step has a confirm button, scans still work).", "type": "string", "enum": [ "scan", "scan_or_tap", "tap" ] }, "paperPickRecord": { "description": "Paper pick lists are the record (default false): the desk may book a batch walked from a printed list as picked (picking_confirm_as_listed), marked as confirmed on paper.", "type": "boolean" }, "fefoEnabled": { "description": "Allocate first-expiring-first-out instead of first-in-first-out (default true). FEFO orders dated lots only; stock without a dated lot keeps the pick route.", "type": "boolean" }, "nearExpiryDays": { "description": "How many days ahead a lot counts as near-expiry (1–3650). Defaults to 30.", "type": "integer", "minimum": 1, "maximum": 3650 }, "qcAtPack": { "description": "Retired: replaced by packChecklist.qc.mode. Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "captureOnFulfill": { "description": "Capture an authorized payment when the order is fulfilled.", "type": "boolean" }, "requireLabelBeforeFulfil": { "description": "Retired: replaced by packChecklist.label.mode. Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "packChecklist": { "description": "The pack checklist: the steps a parcel walks at the pack station (photo, weigh, check, label) and how strongly each is asked for. Absent on a new warehouse: the plan of the first warehouse, else Just pack (scan and fulfil).", "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "preset": { "type": "string", "enum": [ "just_pack", "weigh_label", "proof_photo", "custom" ], "description": "Display only: recomputed from the step modes on every save." }, "photo": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ] }, "retentionDays": { "type": "number", "enum": [ 30, 90, 180, 365 ], "description": "How many days a pack photo is kept (30, 90, 180 or 365)." } }, "required": [ "mode", "retentionDays" ] }, "weigh": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ] }, "tolerancePct": { "type": "integer", "minimum": 5, "maximum": 50, "description": "How far a weight may be off the expected one, in whole percent (5–50)." }, "offPolicy": { "type": "string", "enum": [ "warn", "lead" ], "description": "What a weight outside the tolerance does: \"warn\" (it is saved and shown)." } }, "required": [ "mode", "tolerancePct", "offPolicy" ] }, "qc": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required" ] } }, "required": [ "mode" ] }, "label": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ], "description": "\"required\": no fulfil without a label of the parcel or a tracking number; \"optional\": Fulfil + print buys one when the shipping rules resolve a service, and fulfils without one otherwise; \"off\": the pack station buys none." } }, "required": [ "mode" ] } }, "required": [ "v", "preset", "photo", "weigh", "qc", "label" ] }, "countCadence": { "description": "Scheduled cycle counts by velocity class (default off; A every 7, B every 30, C every 90 days). On, a daily pass creates a count task for every stocked bin whose last approved count is older than its class allows; a bin never counted is due on one day of its class's period, so the first round is spread over it.", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Create cycle counts on this schedule (default off)." }, "days": { "type": "object", "properties": { "A": { "type": "integer", "minimum": 1, "maximum": 365 }, "B": { "type": "integer", "minimum": 1, "maximum": 365 }, "C": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "A", "B", "C" ], "description": "Days between counts of a bin, per velocity class A, B and C (1 to 365)." } }, "required": [ "enabled", "days" ] }, "timeZone": { "description": "The warehouse's IANA time zone (e.g. \"Europe/Berlin\"): its days for shifts and the time clock. Required before the time clock or the first shift pattern is switched on.", "type": "string", "maxLength": 64 }, "timeClock": { "description": "The time clock: \"off\" (the default) or \"on\", which needs a timeZone.", "type": "string", "enum": [ "off", "on" ] }, "gatedFloorActions": { "description": "The floor exceptions that need a lead's PIN in this warehouse. Defaults to all of them.", "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "short_line", "mark_damaged", "close_receipt_short", "accept_count_difference", "confirm_without_scan", "move_allocated", "retarget_move", "release_other" ] } }, "receivingFlow": { "description": "How manual receipts and Logistified purchase orders are received: \"direct\" (the default: straight to a shelf bin), \"dock\" (into DOCK-01, put away later as a floor task) or \"dock_inspect\" (into QC-IN-01 for inspection first). Transfers and finished goods are always received directly. Turning a dock flow on is refused while the warehouse holds a bin of its own coded DOCK-01 or QC-IN-01 (reserved_code_taken).", "type": "string", "enum": [ "direct", "dock", "dock_inspect" ] }, "purchasePrices": { "description": "The purchase-price warning: when a receipt's cost is applied, each item whose cost lies more than tolerancePct from the price its Logistified purchase order agreed is flagged on the receipt. It warns and never refuses. Absent: warn beyond 5 %.", "type": "object", "properties": { "warn": { "type": "boolean", "description": "Flag a receipt whose applied cost deviates from its PO price (default true)." }, "tolerancePct": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How many percent either way a cost may lie from the PO price (default 5)." } }, "required": [ "warn", "tolerancePct" ] }, "inspection": { "description": "The inspection rules of a dock_inspect warehouse: whether a failed unit needs a photo and the warehouse's own fail reasons. Absent: a photo on every fail, no own reasons.", "type": "object", "properties": { "photoOnFail": { "type": "boolean", "description": "A failed inspection needs a photo of the goods (default true)." }, "customReasons": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "description": "The reason's key, stored on the inspection." }, "label": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "key", "label" ] }, "description": "The warehouse's own reasons a unit fails inspection, at most 8." } }, "required": [ "photoOnFail", "customReasons" ] }, "dispatch": { "description": "The packing calendar delivery dates count in (when they are on): how many packing days before the customer's delivery day an order is packed, the days of the week this warehouse packs on and the days it is closed. Defaults to 1 day before, Monday to Friday, no closed days.", "type": "object", "properties": { "packDaysBefore": { "type": "integer", "minimum": 0, "maximum": 7, "description": "Packing days before the delivery day (0–7); 0 packs on the delivery day itself." }, "packingWeekdays": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] }, "description": "The ISO days of the week this warehouse packs on, 1 = Monday … 7 = Sunday." }, "closedDays": { "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Days (YYYY-MM-DD) the warehouse does not pack although the weekday says so; at most 60." } }, "required": [ "packDaysBefore", "packingWeekdays", "closedDays" ] }, "pickOnPackDay": { "description": "Picking waits for the pack day (default false): while delivery dates are on, an order with a requested delivery day is not ready to pick in this warehouse before its pack day, unless someone let it through early (orders_set_pick_early).", "type": "boolean" } }, "required": [ "allowNegative", "overReceiptTolerancePct" ], "additionalProperties": false } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/assign-building": { "post": { "operationId": "warehouses_building_assign", "summary": "warehouses_building_assign", "description": "Assign a physical entity to a storey and explicit walk-up point. Moving a container clears descendant approaches atomically.\n\n**Operation id:** `warehouses_building_assign` — the same operation is `app.warehouses.building_assign({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_building_assign`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "type": "object", "properties": { "entity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "bin" }, "id": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "station" }, "id": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] } ] }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "approach": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 } }, "required": [ "x", "y" ] }, { "type": "null" } ] } }, "required": [ "entity", "storeyId", "approach" ] } }, "required": [ "warehouseId", "expectedRevision", "placement" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/autoprovision": { "post": { "operationId": "warehouses_autoprovision", "summary": "warehouses_autoprovision", "description": "Create one warehouse per active, non-fulfillment-service Shopify location that no warehouse is linked to yet (name = location name, availability writer OFF, cutover state `bootstrap`). Idempotent — existing warehouses and manual mappings are never touched; the install backfill runs the same provisioning automatically when its locations phase completes.\n\n**Operation id:** `warehouses_autoprovision` — the same operation is `app.warehouses.autoprovision({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_autoprovision`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/building": { "get": { "operationId": "warehouses_building_get", "summary": "warehouses_building_get", "description": "Read the versioned warehouse building, storeys, connectors and explicit approach points.\n\n**Operation id:** `warehouses_building_get` — the same operation is `app.warehouses.building_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_building_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/cutover-history": { "get": { "operationId": "warehouses_cutover_history", "summary": "warehouses_cutover_history", "description": "The last three go-live (writer cutover) attempts of one warehouse, newest first: who ran it, when, whether it activated or was blocked (`kind`), the mismatch count and whether mismatches were forced — plus, while the warehouse is not a live writer, its outstanding requirement (`kind: required`; `requiredBy` names what raised it, e.g. a Logistified receiving-ownership proposal that waits on this warehouse's Go live).\n\n**Operation id:** `warehouses_cutover_history` — the same operation is `app.warehouses.cutover_history({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_cutover_history`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/floor-plan": { "get": { "operationId": "warehouses_get_floor_plan", "summary": "warehouses_get_floor_plan", "description": "Read one storey plan and its building revision.\n\n**Operation id:** `warehouses_get_floor_plan` — the same operation is `app.warehouses.get_floor_plan({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_get_floor_plan`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "storeyId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/from-locations": { "post": { "operationId": "warehouses_create_from_locations", "summary": "warehouses_create_from_locations", "description": "Make warehouses from Shopify locations, named after them, in one transaction (at most 20): a location that is unknown, inactive, run by a fulfillment service or already a warehouse refuses the whole batch. The setup guide's one submit; nothing is imported here, each warehouse's Stock step does that.\n\n**Operation id:** `warehouses_create_from_locations` — the same operation is `app.warehouses.create_from_locations({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_create_from_locations`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopifyLocationIds": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "Shopify location ids (numeric or GID) that become warehouses." } }, "required": [ "shopifyLocationIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/overview-bins": { "get": { "operationId": "warehouses_overview_bins", "summary": "warehouses_overview_bins", "description": "A cursor page of active leaf bins in one warehouse with exact on-hand units and unit-capacity utilization. Counts describe this page, not warehouse totals. Unconfigured unit capacity is null; expected inbound never counts as on-hand. An approachSet value means this bin has its own walk-up point; storeyId includes inherited assignments.\n\n**Operation id:** `warehouses_overview_bins` — the same operation is `app.warehouses.overview_bins({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_overview_bins`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 60, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/route-preview": { "get": { "operationId": "warehouses_route_preview", "summary": "warehouses_route_preview", "description": "Preview a bounded physically validated walking path or an explicit unresolved route.\n\n**Operation id:** `warehouses_route_preview` — the same operation is `app.warehouses.route_preview({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_route_preview`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "from", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "x", "y", "storeyId" ] }, { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "bin" }, "id": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "station" }, "id": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] } ] } ] } }, { "name": "to", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "x", "y", "storeyId" ] }, { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "bin" }, "id": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "station" }, "id": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] } ] } ] } }, { "name": "profile", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "walk", "cart" ] } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/set-building": { "post": { "operationId": "warehouses_building_set", "summary": "warehouses_building_set", "description": "Replace the building using its expected revision. Changes never alter physical stock.\n\n**Operation id:** `warehouses_building_set` — the same operation is `app.warehouses.building_set({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_building_set`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "building": { "type": "object", "properties": { "version": { "type": "number", "const": 2 }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "storeys": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "order": { "type": "integer", "minimum": -100, "maximum": 100 }, "metresPerUnit": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, { "type": "null" } ] }, "plan": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "gridSize": { "type": "number", "minimum": 1, "maximum": 1000 }, "wallThickness": { "type": "number", "minimum": 1, "maximum": 200 }, "floors": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 } }, "required": [ "id", "x", "y", "w", "h" ] } }, "walls": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "x1": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y1": { "type": "number", "minimum": -100000, "maximum": 100000 }, "x2": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y2": { "type": "number", "minimum": -100000, "maximum": 100000 } }, "required": [ "id", "x1", "y1", "x2", "y2" ] } } }, "required": [ "version", "gridSize", "wallThickness", "floors", "walls" ] }, "fixtures": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 } }, "required": [ "id", "x", "y", "w", "h" ] } } }, "required": [ "id", "name", "order", "metresPerUnit", "plan", "fixtures" ] } }, "connectors": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "stairs", "lift" ] }, "from": { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "x", "y", "storeyId" ] }, "to": { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "x", "y", "storeyId" ] }, "direction": { "type": "string", "enum": [ "both", "forward" ] }, "enabled": { "type": "boolean" }, "traversalSeconds": { "type": "number", "minimum": 0, "maximum": 3600 } }, "required": [ "id", "name", "kind", "from", "to", "direction", "enabled", "traversalSeconds" ] } }, "placements": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "entity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "bin" }, "id": { "type": "string", "description": "A bins id, e.g. \"bins_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "station" }, "id": { "type": "string", "description": "A stations id, e.g. \"stations_01ARZ3NDEKTSV4RRFFQ69G5FAV\"." } }, "required": [ "kind", "id" ] } ] }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "approach": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 } }, "required": [ "x", "y" ] }, { "type": "null" } ] } }, "required": [ "entity", "storeyId", "approach" ] } } }, "required": [ "version", "revision", "storeys", "connectors", "placements" ] } }, "required": [ "warehouseId", "expectedRevision", "building" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/set-floor-plan": { "post": { "operationId": "warehouses_set_floor_plan", "summary": "warehouses_set_floor_plan", "description": "Replace one storey plan using the expected building revision.\n\n**Operation id:** `warehouses_set_floor_plan` — the same operation is `app.warehouses.set_floor_plan({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_set_floor_plan`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "A warehouses id, e.g. \"warehouses_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "storeyId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "plan": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "gridSize": { "type": "number", "minimum": 1, "maximum": 1000 }, "wallThickness": { "type": "number", "minimum": 1, "maximum": 200 }, "floors": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 } }, "required": [ "id", "x", "y", "w", "h" ] } }, "walls": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "x1": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y1": { "type": "number", "minimum": -100000, "maximum": 100000 }, "x2": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y2": { "type": "number", "minimum": -100000, "maximum": 100000 } }, "required": [ "id", "x1", "y1", "x2", "y2" ] } } }, "required": [ "version", "gridSize", "wallThickness", "floors", "walls" ] } }, "required": [ "warehouseId", "storeyId", "expectedRevision", "plan" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/setup": { "get": { "operationId": "warehouses_setup", "summary": "warehouses_setup", "description": "One warehouse's setup, detected from its data: its steps (bins, stock, live), the next step, its Shopify location and whether units still sit in the unassigned bin. The warehouse page's setup strip; `setup_status` lists the same for every warehouse in setup.\n\n**Operation id:** `warehouses_setup` — the same operation is `app.warehouses.setup({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_setup`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/warehouses/update": { "post": { "operationId": "warehouses_update", "summary": "warehouses_update", "description": "Update name, Shopify location mapping, active flag or settings of a warehouse. `settings.inventoryWriter` turns the Shopify availability push (OMS-032) on for this warehouse — only one system may write a location's inventory, and turning it ON is refused until the warehouse has passed the writer cutover (the 'Go live' verification against live Shopify quantities); turning it OFF demotes the cutover state so re-enabling verifies again. `settings.countCadence` schedules cycle counts by velocity class (off by default); turning it on creates the due counts at once and then daily.\n\n**Operation id:** `warehouses_update` — the same operation is `app.warehouses.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/warehouses_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "warehouses" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "description": "document id of the warehouse.", "format": "floormode-id" }, "name": { "type": "string", "minLength": 1 }, "shopifyLocationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "active": { "type": "boolean" }, "settings": { "type": "object", "properties": { "allowNegative": { "type": "boolean" }, "overReceiptTolerancePct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Over-receipt tolerance in percent of the expected quantity (0–100)." }, "inventoryWriter": { "description": "Push this warehouse's sellable available to Shopify (default false). Turning it ON is refused until the warehouse has passed the writer cutover (warehouses_applyCutover).", "type": "boolean" }, "allowOversell": { "description": "Accept backorders/preorders: a shortfall becomes a backorder (default false).", "type": "boolean" }, "trackLots": { "description": "Retired: replaced by each item's tracking mode (variants_set_tracking). Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "putawayStrategy": { "description": "How new stock is placed: \"together\" (next to the same product, else the emptiest bin; the default) or \"spread\" (prefer bins that do not hold the product yet).", "type": "string", "enum": [ "together", "spread" ] }, "floorConfirm": { "description": "How Floor Mode workers confirm a bin or an item: \"scan\" (a scan or a typed code is required), \"scan_or_tap\" (the default: a device without a scanner may confirm by tapping) or \"tap\" (no scanners: every step has a confirm button, scans still work).", "type": "string", "enum": [ "scan", "scan_or_tap", "tap" ] }, "paperPickRecord": { "description": "Paper pick lists are the record (default false): the desk may book a batch walked from a printed list as picked (picking_confirm_as_listed), marked as confirmed on paper.", "type": "boolean" }, "fefoEnabled": { "description": "Allocate first-expiring-first-out instead of first-in-first-out (default true). FEFO orders dated lots only; stock without a dated lot keeps the pick route.", "type": "boolean" }, "nearExpiryDays": { "description": "How many days ahead a lot counts as near-expiry (1–3650). Defaults to 30.", "type": "integer", "minimum": 1, "maximum": 3650 }, "qcAtPack": { "description": "Retired: replaced by packChecklist.qc.mode. Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "captureOnFulfill": { "description": "Capture an authorized payment when the order is fulfilled.", "type": "boolean" }, "requireLabelBeforeFulfil": { "description": "Retired: replaced by packChecklist.label.mode. Sending it is refused.", "not": { "description": "Any JSON value. This field's zod schema (a transform, a refinement or a custom type) has no exact JSON Schema equivalent, so nothing is asserted about it here — the server still validates it against the operation's own schema and answers 400 with the issue list." } }, "packChecklist": { "description": "The pack checklist: the steps a parcel walks at the pack station (photo, weigh, check, label) and how strongly each is asked for. Absent on a new warehouse: the plan of the first warehouse, else Just pack (scan and fulfil).", "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "preset": { "type": "string", "enum": [ "just_pack", "weigh_label", "proof_photo", "custom" ], "description": "Display only: recomputed from the step modes on every save." }, "photo": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ] }, "retentionDays": { "type": "number", "enum": [ 30, 90, 180, 365 ], "description": "How many days a pack photo is kept (30, 90, 180 or 365)." } }, "required": [ "mode", "retentionDays" ] }, "weigh": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ] }, "tolerancePct": { "type": "integer", "minimum": 5, "maximum": 50, "description": "How far a weight may be off the expected one, in whole percent (5–50)." }, "offPolicy": { "type": "string", "enum": [ "warn", "lead" ], "description": "What a weight outside the tolerance does: \"warn\" (it is saved and shown)." } }, "required": [ "mode", "tolerancePct", "offPolicy" ] }, "qc": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required" ] } }, "required": [ "mode" ] }, "label": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ], "description": "\"required\": no fulfil without a label of the parcel or a tracking number; \"optional\": Fulfil + print buys one when the shipping rules resolve a service, and fulfils without one otherwise; \"off\": the pack station buys none." } }, "required": [ "mode" ] } }, "required": [ "v", "preset", "photo", "weigh", "qc", "label" ] }, "countCadence": { "description": "Scheduled cycle counts by velocity class (default off; A every 7, B every 30, C every 90 days). On, a daily pass creates a count task for every stocked bin whose last approved count is older than its class allows; a bin never counted is due on one day of its class's period, so the first round is spread over it.", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Create cycle counts on this schedule (default off)." }, "days": { "type": "object", "properties": { "A": { "type": "integer", "minimum": 1, "maximum": 365 }, "B": { "type": "integer", "minimum": 1, "maximum": 365 }, "C": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "A", "B", "C" ], "description": "Days between counts of a bin, per velocity class A, B and C (1 to 365)." } }, "required": [ "enabled", "days" ] }, "timeZone": { "description": "The warehouse's IANA time zone (e.g. \"Europe/Berlin\"): its days for shifts and the time clock. Required before the time clock or the first shift pattern is switched on.", "type": "string", "maxLength": 64 }, "timeClock": { "description": "The time clock: \"off\" (the default) or \"on\", which needs a timeZone.", "type": "string", "enum": [ "off", "on" ] }, "gatedFloorActions": { "description": "The floor exceptions that need a lead's PIN in this warehouse. Defaults to all of them.", "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "short_line", "mark_damaged", "close_receipt_short", "accept_count_difference", "confirm_without_scan", "move_allocated", "retarget_move", "release_other" ] } }, "receivingFlow": { "description": "How manual receipts and Logistified purchase orders are received: \"direct\" (the default: straight to a shelf bin), \"dock\" (into DOCK-01, put away later as a floor task) or \"dock_inspect\" (into QC-IN-01 for inspection first). Transfers and finished goods are always received directly. Turning a dock flow on is refused while the warehouse holds a bin of its own coded DOCK-01 or QC-IN-01 (reserved_code_taken).", "type": "string", "enum": [ "direct", "dock", "dock_inspect" ] }, "purchasePrices": { "description": "The purchase-price warning: when a receipt's cost is applied, each item whose cost lies more than tolerancePct from the price its Logistified purchase order agreed is flagged on the receipt. It warns and never refuses. Absent: warn beyond 5 %.", "type": "object", "properties": { "warn": { "type": "boolean", "description": "Flag a receipt whose applied cost deviates from its PO price (default true)." }, "tolerancePct": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How many percent either way a cost may lie from the PO price (default 5)." } }, "required": [ "warn", "tolerancePct" ] }, "inspection": { "description": "The inspection rules of a dock_inspect warehouse: whether a failed unit needs a photo and the warehouse's own fail reasons. Absent: a photo on every fail, no own reasons.", "type": "object", "properties": { "photoOnFail": { "type": "boolean", "description": "A failed inspection needs a photo of the goods (default true)." }, "customReasons": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "description": "The reason's key, stored on the inspection." }, "label": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "key", "label" ] }, "description": "The warehouse's own reasons a unit fails inspection, at most 8." } }, "required": [ "photoOnFail", "customReasons" ] }, "dispatch": { "description": "The packing calendar delivery dates count in (when they are on): how many packing days before the customer's delivery day an order is packed, the days of the week this warehouse packs on and the days it is closed. Defaults to 1 day before, Monday to Friday, no closed days.", "type": "object", "properties": { "packDaysBefore": { "type": "integer", "minimum": 0, "maximum": 7, "description": "Packing days before the delivery day (0–7); 0 packs on the delivery day itself." }, "packingWeekdays": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] }, "description": "The ISO days of the week this warehouse packs on, 1 = Monday … 7 = Sunday." }, "closedDays": { "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Days (YYYY-MM-DD) the warehouse does not pack although the weekday says so; at most 60." } }, "required": [ "packDaysBefore", "packingWeekdays", "closedDays" ] }, "pickOnPackDay": { "description": "Picking waits for the pack day (default false): while delivery dates are on, an order with a requested delivery day is not ready to pick in this warehouse before its pack day, unless someone let it through early (orders_set_pick_early).", "type": "boolean" } }, "required": [ "allowNegative", "overReceiptTolerancePct" ] }, "latitude": { "description": "Geo latitude for distributed order routing (OMS-078); null clears it.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "description": "Geo longitude for distributed order routing (OMS-078); null clears it.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves": { "get": { "operationId": "waves_list", "summary": "waves_list", "description": "Releases (waves), a disclosed page at a time (`rows`/`capped`/`cursor`, max 100), newest first (`created:desc`, the default) or oldest first, each with its attached orders and their planned units. Filters are server predicates: `warehouseId` (the scope) and `statuses` (any of planned, released, closed). `plannedCount` is the scope's exact planned total on page one. Breaking since 2026-10-07: the former single-valued `status` is refused; pass `statuses: [\"planned\"]`.\n\n**Operation id:** `waves_list` — the same operation is `app.waves.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "Only this warehouse's releases; absent = every warehouse.", "schema": { "description": "Only this warehouse's releases; absent = every warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "statuses", "in": "query", "required": false, "description": "Any of planned, released, closed; absent = every status. Repeat the parameter for each element (`?ids=a&ids=b`), or pass a JSON array (`?ids=[\"a\",\"b\"]`) — a JSON array is the only way to send an array of objects.", "style": "form", "explode": true, "schema": { "description": "Any of planned, released, closed; absent = every status.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "planned", "released", "closed" ] } } }, { "name": "sort", "in": "query", "required": false, "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "schema": { "description": "`created:desc` (newest first, the default) or `created:asc` (oldest first).", "type": "string", "enum": [ "created:desc", "created:asc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Releases per page (max 100).", "schema": { "description": "Releases per page (max 100).", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "waves_create", "summary": "waves_create", "description": "Create a planned wave in a warehouse. `cutoffAt` (epoch ms, in the future) is the carrier cutoff: the wave goes to picking by itself at that instant if it is still planned, through the same release rules as waves_release (plan allowance included; a refusal stays on the wave's timeline and the wave stays planned). carrierFilter is advisory planning metadata. The wave starts `planned` — its tasks are held out of the claimable pool until it is released.\n\n**Operation id:** `waves_create` — the same operation is `app.waves.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1 }, "cutoffAt": { "description": "Epoch ms the wave goes to picking by itself; must be in the future.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrierFilter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "warehouseId", "name" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/assign": { "post": { "operationId": "waves_assign", "summary": "waves_assign", "description": "Attach pickable fulfillment orders to a wave: a HELD pick task per FO, carrying the wave id, kept out of the claimable pool until release (WHT-015). Idempotent per allocation and only for pickable FOs (short/held/already-in-pick are skipped). An FO that already has an unclaimed pick task (continuous release) has that task attached to the wave instead — counted as `attached`, not `created`. Returns created/attached/skipped counts (`waveFull` of the skipped: the wave already holds its task bound) and the affected task ids; the skipped FO ids are on the wave timeline.\n\n**Operation id:** `waves_assign` — the same operation is `app.waves.assign({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_assign`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "foDocIds": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "description": "document ids of the fulfillment orders (max 200)." } }, "required": [ "waveId", "foDocIds" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/close": { "post": { "operationId": "waves_close", "summary": "waves_close", "description": "Close a wave: no more work is pulled into it, and every task it still held that is not done or cancelled is unlinked (waveId cleared) and becomes continuous work — a closed wave holds nothing back. Order admission runs first for the affected tasks. Closing an already closed wave repairs anything left held and answers `unlinkedTasks: 0` when nothing was.\n\n**Operation id:** `waves_close` — the same operation is `app.waves.close({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_close`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "waveId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/cutoff": { "post": { "operationId": "waves_set_cutoff", "summary": "waves_set_cutoff", "description": "Move or clear the automatic release of a planned wave. `cutoffAt` (epoch ms, in the future) arms the release for that instant; null clears it, and the wave then waits for waves_release. Refused once the wave was released or closed.\n\n**Operation id:** `waves_set_cutoff` — the same operation is `app.waves.set_cutoff({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_set_cutoff`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "cutoffAt": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Epoch ms the wave goes to picking by itself; null for none." } }, "required": [ "waveId", "cutoffAt" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/delete": { "post": { "operationId": "waves_delete", "summary": "waves_delete", "description": "Delete a wave. Its tasks are unlinked (waveId cleared) rather than cancelled — a held task becomes continuous (claimable), a worked task keeps its history. Returns the number of tasks unlinked.\n\n**Operation id:** `waves_delete` — the same operation is `app.waves.delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "waveId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/get": { "get": { "operationId": "waves_get", "summary": "waves_get", "description": "Get one wave with its task count and open-task count, or null when unknown.\n\n**Operation id:** `waves_get` — the same operation is `app.waves.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "query", "parameters": [ { "name": "waveId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/release": { "post": { "operationId": "waves_release", "summary": "waves_release", "description": "Release a wave: its held tasks become claimable. Returns the wave status and the number of tasks in the wave. Idempotent; rejected once the wave is closed.\n\n**Operation id:** `waves_release` — the same operation is `app.waves.release({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_release`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "waveId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/waves/tasks": { "get": { "operationId": "waves_tasks", "summary": "waves_tasks", "description": "The tasks belonging to a wave (bounded).\n\n**Operation id:** `waves_tasks` — the same operation is `app.waves.tasks({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/waves_tasks`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "waves" ], "x-operation-kind": "query", "parameters": [ { "name": "waveId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks": { "get": { "operationId": "webhook_subscriptions_list", "summary": "webhook_subscriptions_list", "description": "List the outgoing webhook endpoints (at most 10): address, subscribed events, whether it is on and why Floormode switched it off, whether a signing secret is set, and its last delivery. The secret itself is never returned.\n\n**Operation id:** `webhook_subscriptions_list` — the same operation is `app.webhook.subscriptions_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "query", "x-min-plan": "enterprise", "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "webhook_subscriptions_create", "summary": "webhook_subscriptions_create", "description": "Register an HTTPS endpoint for the given events. The address must be public (https on the standard port, no private, local or loopback hosts, no credentials). Answers the endpoint and its signing secret; the secret is shown in this answer only.\n\n**Operation id:** `webhook_subscriptions_create` — the same operation is `app.webhook.subscriptions_create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "shipment.label_purchased", "pack_job.completed", "order.fulfilled", "shipment.delivered", "shipment.delivery_exception", "count.variance_found", "hold.applied", "lot.blocked", "lot.unblocked" ] } }, "active": { "default": true, "type": "boolean" } }, "required": [ "url", "events" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/delete": { "post": { "operationId": "webhook_subscriptions_delete", "summary": "webhook_subscriptions_delete", "description": "Delete an endpoint and its delivery log; deliveries still waiting are dropped.\n\n**Operation id:** `webhook_subscriptions_delete` — the same operation is `app.webhook.subscriptions_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "subscriptionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/deliveries": { "get": { "operationId": "webhook_deliveries_list", "summary": "webhook_deliveries_list", "description": "The newest deliveries of one endpoint: event, status, attempts, the last HTTP status, duration and error kind. Response bodies are never stored.\n\n**Operation id:** `webhook_deliveries_list` — the same operation is `app.webhook.deliveries_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_deliveries_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "query", "x-min-plan": "enterprise", "parameters": [ { "name": "subscriptionId", "in": "query", "required": true, "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "schema": { "type": "string", "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/deliveries/resend": { "post": { "operationId": "webhook_deliveries_resend", "summary": "webhook_deliveries_resend", "description": "Send a delivery that ended `failed` or `expired` again, as a NEW delivery to the same endpoint with the same body: `body.id` (the event id) and `occurredAt` stay, so the receiver deduplicates; `Floormode-Webhook-Id` names the new delivery. Refused unless the endpoint is on, has a secret and is not deleted. The old delivery is unchanged; the new one counts toward switch-off like any other.\n\n**Operation id:** `webhook_deliveries_resend` — the same operation is `app.webhook.deliveries_resend({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_deliveries_resend`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string", "description": "A webhookDeliveries id, e.g. \"webhookDeliveries_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "deliveryId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/rotate-secret": { "post": { "operationId": "webhook_subscriptions_rotate_secret", "summary": "webhook_subscriptions_rotate_secret", "description": "Replace an endpoint's signing secret. The old secret stops signing at once; the new one is shown in this answer only.\n\n**Operation id:** `webhook_subscriptions_rotate_secret` — the same operation is `app.webhook.subscriptions_rotate_secret({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_rotate_secret`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "subscriptionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/test": { "post": { "operationId": "webhook_subscriptions_test", "summary": "webhook_subscriptions_test", "description": "Send one signed `webhook.test` event to an endpoint that is on, whatever it subscribed to. Answers the delivery id; watch it in webhook_deliveries_list.\n\n**Operation id:** `webhook_subscriptions_test` — the same operation is `app.webhook.subscriptions_test({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_test`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" } }, "required": [ "subscriptionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/update": { "post": { "operationId": "webhook_subscriptions_update", "summary": "webhook_subscriptions_update", "description": "Change an endpoint's address, events or on/off switch. A new address is checked like a new endpoint; switching it back on clears the failure count.\n\n**Operation id:** `webhook_subscriptions_update` — the same operation is `app.webhook.subscriptions_update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/webhook_subscriptions_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** `enterprise` (feature `external_api`). The whole external API additionally requires the Enterprise plan (403 `plan_required`).", "tags": [ "webhooks" ], "x-operation-kind": "mutation", "x-min-plan": "enterprise", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "A webhookSubscriptions id, e.g. \"webhookSubscriptions_01ARZ3NDEKTSV4RRFFQ69G5FAV\".", "format": "floormode-id" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "shipment.label_purchased", "pack_job.completed", "order.fulfilled", "shipment.delivered", "shipment.delivery_exception", "count.variance_found", "hold.applied", "lot.blocked", "lot.unblocked" ] } }, "active": { "type": "boolean" } }, "required": [ "subscriptionId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/work/assign": { "post": { "operationId": "work_assign", "summary": "work_assign", "description": "Give a piece of floor work to a person, or take it yourself — the one assignment door (people Round 6). `ref` names the work: a task, a pickBatch, a countTask or a receipt (a packJob is taken by scanning it at a bench, never handed out: pack_job_self_only). personId is a person (people_list). Taking unassigned work for yourself needs the work type's floor permission; giving it to anyone else, or taking work someone holds, needs fulfillment.assign, and started work also `force` (it starts over with its new holder). The person must be active, have the work's warehouse, and their role (narrowed by their worker profile's canDo) must do the work type: refused not_eligible with details.reason inactive | warehouse | task_type. Finished or cancelled work is work_closed; started work without force is already_started. Replaces tasks_assign, tasks_reassign and tasks_release.\n\n**Operation id:** `work_assign` — the same operation is `app.work.assign({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/work_assign`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "work" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "task", "pickBatch", "packJob", "countTask", "receipt" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "id" ] }, "personId": { "description": "The person (people_list); omitted = the caller (Take).", "type": "string", "format": "floormode-id" }, "force": { "description": "Also move started work (fulfillment.assign).", "type": "boolean" } }, "required": [ "ref" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/work/release": { "post": { "operationId": "work_release", "summary": "work_release", "description": "Put a piece of floor work back in the pool (people Round 6). Your own unstarted work goes back under its floor permission; anyone else's, started work, or a pack job needs fulfillment.assign. On a floor device, releasing someone else's work is a gated floor exception (release_other) that takes a lead's approvalId.\n\n**Operation id:** `work_release` — the same operation is `app.work.release({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/work_release`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "work" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "task", "pickBatch", "packJob", "countTask", "receipt" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "id" ] }, "approvalId": { "description": "A lead's single-use grant for release_other (a floor device).", "type": "string", "format": "floormode-id" } }, "required": [ "ref" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/worker-profiles": { "get": { "operationId": "worker_profiles_list", "summary": "worker_profiles_list", "description": "List the worker profiles of a warehouse (max 200): each binds a person (userId) to their assigned zones, home station, the task types they can do and their skill tags. This is what the auto-assignment filters the claimable pool by. Inactive hidden unless includeInactive. pickDefault is the person's default pick profile and lock as the floor applies them now: null and unlocked once the profile is archived, or while the plan does not allow it (lockPaused: plan).\n\n**Operation id:** `worker_profiles_list` — the same operation is `app.worker.profiles_list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/worker_profiles_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "worker-profiles" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "includeInactive", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "worker_profiles_upsert", "summary": "worker_profiles_upsert", "description": "Create or replace a worker's profile in a warehouse (idempotent on tenant + userId + warehouse). userId defaults to the calling user. assignedZoneIds and assignedStationId must belong to the warehouse; canDo is the task types (receive, putaway, pick, pack, count, replenish, move); skills are free-form tags. pickProfileId is the person's default pick profile here (a live profile of this warehouse, null for any; an archived one is refused) and pickProfileLocked keeps them to it on the floor (it needs a default; clearing the default clears it). Omitted fields keep their stored value on an update. userId must be an active person (people_list), else not_found. A person kept to listed warehouses is never given a warehouse here (warehouse_not_granted: people_update gives warehouses); nobody changes their own canDo (own_role_or_scope); a task type needs the floor permission the caller holds (exceeds_own_permissions).\n\n**Operation id:** `worker_profiles_upsert` — the same operation is `app.worker.profiles_upsert({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/worker_profiles_upsert`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "worker-profiles" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "userId": { "description": "The person (people_list); defaults to the calling user.", "type": "string", "format": "floormode-id" }, "assignedZoneIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "assignedStationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "canDo": { "type": "array", "items": { "type": "string", "enum": [ "receive", "putaway", "pick", "pack", "count", "replenish", "move" ] } }, "skills": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "pickProfileId": { "description": "document id of the pick profile.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "pickProfileLocked": { "type": "boolean" } }, "required": [ "warehouseId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/worker-profiles/delete": { "post": { "operationId": "worker_profiles_delete", "summary": "worker_profiles_delete", "description": "Delete a worker profile by document id.\n\n**Operation id:** `worker_profiles_delete` — the same operation is `app.worker.profiles_delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/worker_profiles_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "worker-profiles" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workerProfileId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "workerProfileId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/worker-profiles/get": { "get": { "operationId": "worker_profiles_get", "summary": "worker_profiles_get", "description": "Get the profile of one worker in a warehouse. userId defaults to the calling user, so a worker can read their own assignment. Returns null when no profile exists. pickDefault is the default pick profile and lock as the floor applies them now.\n\n**Operation id:** `worker_profiles_get` — the same operation is `app.worker.profiles_get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/worker_profiles_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "worker-profiles" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": true, "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim.", "schema": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, { "name": "userId", "in": "query", "required": false, "description": "Defaults to the calling user.", "schema": { "description": "Defaults to the calling user.", "type": "string", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/zones": { "get": { "operationId": "zones_list", "summary": "zones_list", "description": "List a warehouse's zones (max 200), the organizational grouping over locations. Each zone has a code, name, optional default station (routing depot), optional storage attributes (temperature, hazmat, secure) and its active flag. Filter by warehouse; inactive zones are hidden unless includeInactive.\n\n**Operation id:** `zones_list` — the same operation is `app.zones.list({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_list`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "query", "parameters": [ { "name": "warehouseId", "in": "query", "required": false, "description": "document id of the warehouse.", "schema": { "description": "document id of the warehouse.", "type": "string", "format": "floormode-id" } }, { "name": "includeInactive", "in": "query", "required": false, "description": "Accepted spellings: `true`, `false`, `1`, `0`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "zones_create", "summary": "zones_create", "description": "Create a zone in a warehouse. The code is uppercased and must be unique in the warehouse; name defaults to the code. Optionally set a default station (the routing depot for tours through the zone) and storage attributes (temperature, hazmat, secure).\n\n**Operation id:** `zones_create` — the same operation is `app.zones.create({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_create`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "defaultStationId": { "description": "document id of a station.", "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "temperature": { "type": "string", "enum": [ "ambient", "chilled", "frozen" ] }, "hazmat": { "type": "boolean" }, "secure": { "type": "boolean" }, "active": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "warehouseId", "code" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/zones/assign-bin": { "post": { "operationId": "zones_assign_bin", "summary": "zones_assign_bin", "description": "Link a location to a zone (zoneId null clears the link). Keeps the location's free-string zone in sync with the zone's code so the serpentine / coordinate routing groups the leaf by that code — no change to the routing signature.\n\n**Operation id:** `zones_assign_bin` — the same operation is `app.zones.assign_bin({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_assign_bin`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "binId": { "type": "string", "description": "document id of the location (bin) node.", "format": "floormode-id" }, "zoneId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ], "description": "document id of the zone, or null to clear." } }, "required": [ "binId", "zoneId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/zones/delete": { "post": { "operationId": "zones_delete", "summary": "zones_delete", "description": "Delete a zone. Locations pointing at it are unlinked first (bounded scan); their free-string zone is left untouched so routing keeps grouping them unchanged.\n\n**Operation id:** `zones_delete` — the same operation is `app.zones.delete({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_delete`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "mutation", "x-irreversible": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "zoneId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." } }, "required": [ "zoneId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/zones/get": { "get": { "operationId": "zones_get", "summary": "zones_get", "description": "Get one zone by document id, or null when unknown.\n\n**Operation id:** `zones_get` — the same operation is `app.zones.get({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_get`.\n\n**Kind:** query — reads only, safe to retry.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "query", "parameters": [ { "name": "zoneId", "in": "query", "required": true, "description": "document id of the zone.", "schema": { "type": "string", "description": "document id of the zone.", "format": "floormode-id" } } ], "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/zones/update": { "post": { "operationId": "zones_update", "summary": "zones_update", "description": "Update a zone: name, code (re-uppercased, must stay unique), default station (null clears), storage attributes (temperature/hazmat/secure — null clears) and the active flag. Only the fields you pass change.\n\n**Operation id:** `zones_update` — the same operation is `app.zones.update({…})` inside the MCP `run` code-mode surface (the first `_` becomes the dot) and the SPA's `POST /api/rpc/zones_update`.\n\n**Kind:** mutation — writes; one atomic transaction.\n\n**Minimum plan:** none beyond the Enterprise plan the whole external API requires (403 `plan_required`).", "tags": [ "zones" ], "x-operation-kind": "mutation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "zoneId": { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, "name": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1 }, "defaultStationId": { "anyOf": [ { "type": "string", "format": "floormode-id", "description": "Opaque identifier string — a table-prefixed ULID such as `orders_01ARZ…`, or the channel's own id where the operation says so. Never parse it; pass it back verbatim." }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "string", "enum": [ "ambient", "chilled", "frozen" ] }, { "type": "null" } ] }, "hazmat": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "zoneId" ] } } } }, "responses": { "200": { "description": "The operation succeeded. The result is under `data`; its shape is the operation's own return value (see the description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A WorkOS OAuth access token (external callers and agents) or a Shopify session token (the embedded app). See the introduction." } }, "schemas": { "Envelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The operation's result. Its shape is declared on the handler (the tenant object's return contract) rather than in the published registry, so it is not constrained here; the operation's description states what comes back." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable message. Safe to show a user." }, "code": { "type": "string", "enum": [ "conflict", "forbidden", "internal", "invalid_input", "invalid_output", "not_found", "organization_changed", "payload_too_large", "unauthorized", "unknown_function" ], "description": "Present when the failure is a domain refusal the tenant object classified. Branch on this, never on the message." } } }, "InvalidInputError": { "type": "object", "required": [ "error", "issues" ], "properties": { "error": { "type": "string", "const": "Invalid input" }, "issues": { "type": "array", "description": "The zod issue list, verbatim: which field failed and why.", "items": { "type": "object", "required": [ "code", "path", "message" ], "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "type": [ "string", "number" ] }, "description": "Path to the offending value inside the input." }, "message": { "type": "string" } } } } } }, "UnknownParameterError": { "type": "object", "required": [ "error", "code", "unknown", "accepted" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "unknown_parameter" }, "unknown": { "type": "array", "items": { "type": "string" }, "description": "The query parameters this operation does not declare." }, "accepted": { "type": "array", "items": { "type": "string" }, "description": "Every parameter name the operation does accept." } } }, "PlanRequiredError": { "type": "object", "required": [ "error", "code", "requiredPlan" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "plan_required" }, "requiredPlan": { "type": "string", "description": "The plan tier the caller needs. The external API requires `enterprise`." } } }, "OperationsCatalog": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEntry" } } } }, "CatalogEntry": { "type": "object", "required": [ "name", "description", "kind", "method", "path", "inputSchema" ], "properties": { "name": { "type": "string", "description": "Operation id, e.g. `orders_list`." }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "mutation", "query" ] }, "method": { "type": "string", "enum": [ "DELETE", "GET", "PATCH", "POST", "PUT" ] }, "path": { "type": "string", "description": "Full path, e.g. `/api/v1/orders`." }, "minPlan": { "type": "string", "description": "Omitted when every tier may call it." }, "irreversible": { "type": "boolean", "description": "Present (true) when a second call cannot undo the first: money, payouts, ledger applications, deletes, cancellations. Confirm with the operator before calling." }, "inputSchema": { "type": "object", "description": "JSON Schema for the operation's input, converted from its zod schema." } } } }, "responses": { "BadRequest": { "description": "The request could not be answered as asked. Either the input failed the operation's schema (`issues` names the fields), or — on `GET`/`DELETE` — it carried a query parameter the operation does not declare, which is refused rather than ignored. Domain codes with this status: `invalid_input`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InvalidInputError" }, { "$ref": "#/components/schemas/UnknownParameterError" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "Conflict": { "description": "Domain refusal. Codes with this status: `conflict`, `organization_changed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated, but not allowed. Either the wrong actor type for this operation, or a plan refusal (`plan_required`): the external API requires the Enterprise plan, and a gated operation additionally requires its published `x-min-plan`. Domain codes with this status: `forbidden`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PlanRequiredError" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "InternalServerError": { "description": "Domain refusal. Codes with this status: `internal`, `invalid_output`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Either the addressed row does not exist, or the authenticated shop has no tenant in the registry. Domain codes with this status: `not_found`, `unknown_function`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "Domain refusal. Codes with this status: `payload_too_large`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "The store's calls for this minute are used up (`rate_limited`). Nothing was run: wait the `Retry-After` seconds and send the same call again.", "headers": { "Retry-After": { "description": "Seconds until the store's quota allows calls again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No usable identity. Either no `Authorization` header and no session cookie, or a token that did not verify. Domain codes with this status: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }