{
    "openapi": "3.1.0",
    "info": {
        "title": "Sobocoo API",
        "description": "Inventory over HTTPS for your own software. Authenticate with a\ncompany **service account** (created by the Account Holder under\nCompany → API access): exchange its client id and secret at\n`POST /api/v1/token` for a one-hour bearer token, then send\n`Authorization: Bearer <access_token>` on every request.\n\nScopes: `inventory:read` (reads) and `inventory:write` (writes;\nalso needs an active subscription). Every response carries\n`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`;\na `429` carries `Retry-After`. Errors are RFC 9457\n`application/problem+json` with a stable `code`. Money is integer\ncents in the company's currency; times are ISO 8601 UTC.\n",
        "version": "1.0.0"
    },
    "paths": {
        "/api/v1/items": {
            "get": {
                "tags": [
                    "Items"
                ],
                "summary": "List items",
                "description": "Keyset-paginated: follow `links.next` / `links.prev`; `after` and `before` are opaque cursors.",
                "operationId": "get_api_v1_items",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Matches name, SKU or UPC.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "description": "Only items at this site (an id from GET /api/v1/sites). Default: every site.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "low_stock",
                        "in": "query",
                        "description": "Only items at or below their reorder point.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "archived",
                        "in": "query",
                        "description": "Include archived items.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "name",
                            "enum": [
                                "name",
                                "sku",
                                "quantity",
                                "updated"
                            ]
                        }
                    },
                    {
                        "name": "order",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "asc",
                            "enum": [
                                "asc",
                                "desc"
                            ]
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "enum": [
                                25,
                                50,
                                100
                            ]
                        }
                    },
                    {
                        "name": "after",
                        "in": "query",
                        "description": "Cursor from links.next.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "before",
                        "in": "query",
                        "description": "Cursor from links.prev.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of items.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Item"
                                            }
                                        },
                                        "links": {
                                            "properties": {
                                                "self": {
                                                    "type": "string"
                                                },
                                                "next": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ]
                                                },
                                                "prev": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "per_page": {
                                                    "type": "integer"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "sort": {
                                                    "type": "string"
                                                },
                                                "order": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Items"
                ],
                "summary": "Create an item",
                "description": "Needs inventory:write and an active subscription. A Sobocoo code is assigned. `initial_quantity` records an opening count in the ledger. `site_id` picks the site (default: the company's default site); an item never changes site.",
                "operationId": "post_api_v1_item_create",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/ItemWrite"
                                    },
                                    {
                                        "required": [
                                            "name"
                                        ],
                                        "properties": {
                                            "initial_quantity": {
                                                "description": "Opening quantity on hand.",
                                                "type": "integer",
                                                "minimum": 0
                                            },
                                            "site_id": {
                                                "description": "The site to stock it at (GET /api/v1/sites). Default: the default site.",
                                                "type": "integer"
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created; Location points at it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/lookup": {
            "get": {
                "tags": [
                    "Items"
                ],
                "summary": "Find an item by scanned code",
                "description": "Accepts what a scanner reads: a Sobocoo QR URL or 12-character code, a UPC-A / EAN-13 / EAN-8 / GTIN-14, or a SKU.",
                "operationId": "get_api_v1_item_lookup",
                "parameters": [
                    {
                        "name": "code",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "036000291452"
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "description": "Look only at this site. Default: every site (a SKU or UPC stocked at several sites matches the first).",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The item and how the code was read.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        },
                                        "scan": {
                                            "properties": {
                                                "kind": {
                                                    "type": "string",
                                                    "enum": [
                                                        "sobocoo",
                                                        "upc_a",
                                                        "ean_13",
                                                        "ean_8",
                                                        "gtin_14",
                                                        "raw"
                                                    ]
                                                },
                                                "code": {
                                                    "type": "string"
                                                },
                                                "checksum_ok": {
                                                    "type": [
                                                        "boolean",
                                                        "null"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nothing matches (code unknown_code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/{id}": {
            "get": {
                "tags": [
                    "Items"
                ],
                "summary": "Get an item",
                "operationId": "get_api_v1_item",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The item.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Items"
                ],
                "summary": "Update an item",
                "description": "Partial: only the fields sent change. Quantity is the ledger's: use movements or a count.",
                "operationId": "patch_api_v1_item_update",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ItemWrite"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The updated item.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/{id}/archive": {
            "post": {
                "tags": [
                    "Items"
                ],
                "summary": "Archive an item",
                "description": "Hidden from lists and refuses movements until restored; nothing is deleted.",
                "operationId": "post_api_v1_item_archive",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The item.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/{id}/unarchive": {
            "post": {
                "tags": [
                    "Items"
                ],
                "summary": "Restore an archived item",
                "operationId": "post_api_v1_item_unarchive",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The item.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/me": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Who am I",
                "description": "The service account behind the token, its effective scopes and its company. A cheap connectivity check.",
                "operationId": "get_api_v1_me",
                "responses": {
                    "200": {
                        "description": "The service account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "client_id": {
                                            "type": "string"
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "scopes": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "company": {
                                            "properties": {
                                                "id": {
                                                    "type": "integer"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "currency": {
                                                    "type": "string"
                                                },
                                                "timezone": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/{id}/movements": {
            "get": {
                "tags": [
                    "Stock"
                ],
                "summary": "An item's ledger",
                "description": "Movements newest first within a range (default the last 90 days).",
                "operationId": "get_api_v1_item_movements",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/from"
                    },
                    {
                        "$ref": "#/components/parameters/to"
                    },
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/offset"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Movements.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Movement"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "offset": {
                                                    "type": "integer"
                                                },
                                                "from": {
                                                    "type": "string"
                                                },
                                                "to": {
                                                    "type": "string"
                                                },
                                                "quantity_on_hand": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Stock"
                ],
                "summary": "Record a movement",
                "description": "Receive, issue, sell or adjust. A receive with comp: true is free units (samples, promos, donations): unit cost 0, comp_value_cents per unit (default the item's unit cost), item cost unchanged. Refusals are 422 with a code: insufficient_stock (below zero without allow_negative), invalid_movement (a sale on an item not for resale, a zero adjust...), item_archived.",
                "operationId": "post_api_v1_item_movement_create",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MovementWrite"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Recorded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Movement"
                                        },
                                        "quantity_on_hand": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/movements": {
            "get": {
                "tags": [
                    "Stock"
                ],
                "summary": "Company-wide movement feed",
                "description": "Every movement in the company within a range, newest first; optionally one type.",
                "operationId": "get_api_v1_movements",
                "parameters": [
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "receive",
                                "issue",
                                "sale",
                                "adjust"
                            ]
                        }
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "description": "Only this site (an id from GET /api/v1/sites). Default: every site.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/from"
                    },
                    {
                        "$ref": "#/components/parameters/to"
                    },
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/offset"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Movements.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Movement"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/items/{id}/count": {
            "post": {
                "tags": [
                    "Stock"
                ],
                "summary": "Set a counted quantity",
                "description": "A physical count: the ledger gets one adjust for the difference (201), or nothing when the count already matches (200, changed=false).",
                "operationId": "post_api_v1_item_count",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "count"
                                ],
                                "properties": {
                                    "count": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Adjusted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Movement"
                                        },
                                        "quantity_on_hand": {
                                            "type": "integer"
                                        },
                                        "changed": {
                                            "type": "boolean"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Already at that count.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "null"
                                        },
                                        "quantity_on_hand": {
                                            "type": "integer"
                                        },
                                        "changed": {
                                            "type": "boolean"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/order-list": {
            "get": {
                "tags": [
                    "Order list"
                ],
                "summary": "The order list",
                "operationId": "get_api_v1_order_list",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "description": "active = open or ordered; closed = the last 100 received/dismissed.",
                        "schema": {
                            "type": "string",
                            "default": "active",
                            "enum": [
                                "active",
                                "closed"
                            ]
                        }
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "description": "Only this site (an id from GET /api/v1/sites). Default: every site.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Entries.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/OrderListEntry"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Order list"
                ],
                "summary": "Add an item to the order list",
                "description": "Merged into the item's open entry when there is one. Omit quantity for the suggested one (back above the reorder point).",
                "operationId": "post_api_v1_order_list_add",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "item_id"
                                ],
                                "properties": {
                                    "item_id": {
                                        "type": "integer"
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "minimum": 1
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/order-list/{id}": {
            "get": {
                "tags": [
                    "Order list"
                ],
                "summary": "Get an entry",
                "operationId": "get_api_v1_order_list_entry",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Order list"
                ],
                "summary": "Change the quantity",
                "operationId": "patch_api_v1_order_list_update",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "quantity"
                                ],
                                "properties": {
                                    "quantity": {
                                        "type": "integer",
                                        "minimum": 1
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/order-list/{id}/ordered": {
            "post": {
                "tags": [
                    "Order list"
                ],
                "summary": "Mark ordered",
                "operationId": "post_api_v1_order_list_ordered",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reference": {
                                        "description": "Supplier reference / invoice number.",
                                        "type": "string",
                                        "maxLength": 80
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/order-list/{id}/received": {
            "post": {
                "tags": [
                    "Order list"
                ],
                "summary": "Mark received",
                "description": "Records the receive movement (unit cost defaults to the item's; quantity to what was ordered) and closes the entry.",
                "operationId": "post_api_v1_order_list_received",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "unit_cost_cents": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "minimum": 1
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The entry and the movement.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        },
                                        "movement": {
                                            "$ref": "#/components/schemas/Movement"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/order-list/{id}/dismiss": {
            "post": {
                "tags": [
                    "Order list"
                ],
                "summary": "Dismiss an entry",
                "operationId": "post_api_v1_order_list_dismiss",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/OrderListEntry"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders": {
            "get": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "List purchase orders",
                "description": "Newest first, 25 per page, without lines (with tracking numbers).",
                "operationId": "get_api_v1_purchase_orders",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "all",
                            "enum": [
                                "all",
                                "open",
                                "received"
                            ]
                        }
                    },
                    {
                        "name": "tracking",
                        "in": "query",
                        "description": "Only the order holding this tracking number (spaces, dashes and case are ignored).",
                        "schema": {
                            "type": "string",
                            "maxLength": 80
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "description": "Only this site (an id from GET /api/v1/sites). Default: every site.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of orders.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/PurchaseOrder"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                },
                                                "per_page": {
                                                    "type": "integer"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Create a purchase order",
                "description": "Lines may point at open order-list entries, which become \"ordered\". Every line must be an item of the same site; the order stocks that site. The number must be unique in the company (code duplicate_number). Give the supplier as vendor_id (from GET /api/v1/vendors) or as a supplier name: a name matches a vendor case-insensitively, or is added as a new vendor. vendor_id wins when both are sent. Archived vendors are refused (code invalid_order). Optional tracking numbers go on the order with it; one already on an order of the company is refused (code duplicate_tracking).",
                "operationId": "post_api_v1_purchase_order_create",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "number",
                                    "lines"
                                ],
                                "properties": {
                                    "number": {
                                        "type": "string",
                                        "example": "PO-1042",
                                        "maxLength": 80
                                    },
                                    "vendor_id": {
                                        "type": "integer"
                                    },
                                    "supplier": {
                                        "description": "A vendor name, matched or added.",
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 2000
                                    },
                                    "ordered_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "item_id",
                                                "quantity",
                                                "expected_unit_cost_cents"
                                            ],
                                            "properties": {
                                                "item_id": {
                                                    "type": "integer"
                                                },
                                                "quantity": {
                                                    "type": "integer",
                                                    "minimum": 1
                                                },
                                                "expected_unit_cost_cents": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_comp": {
                                                    "description": "Comp (free) units on top of quantity; never in the totals.",
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "order_list_entry_id": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 200,
                                        "minItems": 1
                                    },
                                    "fees": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "label",
                                                "amount_cents"
                                            ],
                                            "properties": {
                                                "label": {
                                                    "type": "string"
                                                },
                                                "amount_cents": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 20
                                    },
                                    "tracking": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/PurchaseOrderTrackingWrite"
                                        },
                                        "maxItems": 50
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}": {
            "get": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Get a purchase order",
                "operationId": "get_api_v1_purchase_order",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The order with lines and fees.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Edit supplier or notes",
                "description": "Change the vendor with vendor_id, or with a supplier name (matched case-insensitively or added as a new vendor); null for either clears it. Fields left out are unchanged.",
                "operationId": "patch_api_v1_purchase_order_update",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "vendor_id": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    },
                                    "supplier": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 120
                                    },
                                    "notes": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 2000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The order.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}/receive": {
            "post": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Record a delivery",
                "description": "Good units go into stock at the actual unit cost (which becomes the item's unit cost); damaged and returned units are counted, never stocked. comp_received free units go into stock as a $0 receive carrying their value (the item's unit cost does not change); comp_damaged are counted only. More than outstanding (paid or comp) is refused unless allow_over (code invalid_receipt). Name the box the delivery came in with tracking (a number as typed or scanned, label barcodes included) or tracking_id (a row of this order's tracking array), not both: that number is marked received (its received_at) with the delivery. A number on another order of the company is refused (code tracking_not_on_order, the detail names the order); one the company does not have is code unknown_tracking.",
                "operationId": "post_api_v1_purchase_order_receive",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "lines"
                                ],
                                "properties": {
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "line_id"
                                            ],
                                            "properties": {
                                                "line_id": {
                                                    "type": "integer"
                                                },
                                                "received": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "damaged": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "returned": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "actual_unit_cost_cents": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "return_reason": {
                                                    "type": "string"
                                                },
                                                "comp_received": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "comp_damaged": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "minItems": 1
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255
                                    },
                                    "allow_over": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "tracking": {
                                        "description": "The tracking number the delivery came under, as typed or scanned (spaces, dashes and case ignored; a carrier label barcode payload is unpacked).",
                                        "type": "string",
                                        "example": "1Z 999 AA1 0123 4567 84",
                                        "maxLength": 200
                                    },
                                    "tracking_id": {
                                        "description": "Or the id of one of this order's tracking rows.",
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The order after the delivery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        },
                                        "stocked": {
                                            "description": "Units put into stock by this call.",
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}/close": {
            "post": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Close an order",
                "description": "Writes off whatever is still outstanding (code not_receivable when already closed).",
                "operationId": "post_api_v1_purchase_order_close",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The closed order.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}/correct": {
            "patch": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Correct an order",
                "description": "Fix an order after the fact, at any status (open, partial, received or closed): what the web app's Edit order form changes, with the same rules and results. Every field is optional; a field left out keeps its stored value, and so does a line left out of lines or a line field left out of its object. fees, when sent, is the full new fee list ([] removes every fee). Line fields use the names of the line resource, so a line read from GET can be edited and sent back. Unknown fields are refused (the order number cannot change). A change in quantity_received moves stock by the difference, referenced \"PO <number>\": more is a receive at the price paid, fewer an adjustment (it may take stock below zero); quantity_comp_received does the same with $0 comp receives. A changed price paid (above $0) becomes the item's unit cost. A changed received_at re-dates the delivery that completed the order. Unless the order is closed, its status follows the lines. remove: true takes a line off the order once its counts (free units too) are 0, and puts its order-list entry back on the list; the last line cannot be removed (close the order instead). One purchase_order.edited audit entry lists every change; each tracking number added or removed is audited on its own. Refusals are 422 with code invalid_correction (or duplicate_tracking / invalid_tracking for tracking.add) and the same message as the web form.",
                "operationId": "patch_api_v1_purchase_order_correct",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "vendor_id": {
                                        "description": "A vendor from GET /api/v1/vendors; wins over supplier. null (with no supplier) clears the supplier.",
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    },
                                    "supplier": {
                                        "description": "A vendor name, matched case-insensitively or added as a new vendor.",
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 120
                                    },
                                    "notes": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 2000
                                    },
                                    "ordered_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "received_at": {
                                        "description": "When the order was received; not in the future. Kept to the minute you send (the web form uses quarter hours).",
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "line_id"
                                            ],
                                            "properties": {
                                                "line_id": {
                                                    "description": "The id of a line of this order.",
                                                    "type": "integer"
                                                },
                                                "quantity_ordered": {
                                                    "type": "integer",
                                                    "minimum": 1
                                                },
                                                "expected_unit_cost_cents": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_received": {
                                                    "description": "Good units received in total (not a delta).",
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_damaged": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_returned": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "actual_unit_cost_cents": {
                                                    "description": "The price paid per unit; null = the expected one.",
                                                    "type": [
                                                        "integer",
                                                        "null"
                                                    ],
                                                    "minimum": 0
                                                },
                                                "return_reason": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "maxLength": 255
                                                },
                                                "quantity_comp": {
                                                    "description": "Comp (free) units promised.",
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_comp_received": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "quantity_comp_damaged": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                },
                                                "remove": {
                                                    "description": "Take the line off the order (its counts must be 0).",
                                                    "type": "boolean",
                                                    "default": false
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 200
                                    },
                                    "fees": {
                                        "description": "The full new fee list.",
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "label",
                                                "amount_cents"
                                            ],
                                            "properties": {
                                                "label": {
                                                    "type": "string"
                                                },
                                                "amount_cents": {
                                                    "type": "integer",
                                                    "minimum": 0
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 20
                                    },
                                    "tracking": {
                                        "properties": {
                                            "add": {
                                                "type": "array",
                                                "items": {
                                                    "$ref": "#/components/schemas/PurchaseOrderTrackingWrite"
                                                }
                                            },
                                            "remove": {
                                                "description": "Ids of this order's tracking rows.",
                                                "type": "array",
                                                "items": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The order after the correction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        },
                                        "changed": {
                                            "description": "false when the request changed nothing.",
                                            "type": "boolean"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}/tracking": {
            "post": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Add a tracking number",
                "description": "The number is normalized (uppercase, spaces and dashes removed) and its carrier detected from the format (UPS 1Z..., FedEx, USPS, DHL) unless carrier is given. A number already on an order of the company is refused (code duplicate_tracking, the detail names the order); an unreadable one is code invalid_tracking. At most 50 per order.",
                "operationId": "post_api_v1_purchase_order_tracking_add",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PurchaseOrderTrackingWrite"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Added. data is the order with its tracking; tracking is the new row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        },
                                        "tracking": {
                                            "$ref": "#/components/schemas/PurchaseOrderTracking"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/purchase-orders/{id}/tracking/{trackingId}": {
            "delete": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Remove a tracking number",
                "operationId": "delete_api_v1_purchase_order_tracking_remove",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    },
                    {
                        "name": "trackingId",
                        "in": "path",
                        "description": "The id of a tracking row of this order.",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed; the order without it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Purchase orders"
                ],
                "summary": "Edit a tracking number",
                "description": "Change the carrier or the note; the number itself never changes (remove it and add the right one). carrier null detects the carrier from the number again; note null or empty clears it. Fields left out are unchanged. A real change is in the audit trail with before and after.",
                "operationId": "patch_api_v1_purchase_order_tracking_edit",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    },
                    {
                        "name": "trackingId",
                        "in": "path",
                        "description": "The id of a tracking row of this order.",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "carrier": {
                                        "description": "null: detect it from the number.",
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "enum": [
                                            "ups",
                                            "fedex",
                                            "usps",
                                            "dhl",
                                            "other"
                                        ]
                                    },
                                    "note": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 200
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "data is the order with its tracking; tracking is the edited row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        },
                                        "tracking": {
                                            "$ref": "#/components/schemas/PurchaseOrderTracking"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/Validation"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/sites": {
            "get": {
                "tags": [
                    "Sites"
                ],
                "summary": "List sites",
                "description": "Every active site of the company, default first. A service account sees every site.",
                "operationId": "get_api_v1_sites",
                "responses": {
                    "200": {
                        "description": "The sites.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Site"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/token": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Exchange a service account's credentials for a bearer token",
                "description": "OAuth 2.0 client_credentials. Send the fields as JSON, as a form body, or the client id and secret as HTTP Basic. Tokens last one hour; get a new one when one expires. Failed exchanges are throttled per IP and per client id.",
                "operationId": "post_api_v1_token",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "client_id",
                                    "client_secret"
                                ],
                                "properties": {
                                    "grant_type": {
                                        "type": "string",
                                        "default": "client_credentials",
                                        "enum": [
                                            "client_credentials"
                                        ]
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "example": "sbc_4Kq9..."
                                    },
                                    "client_secret": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TokenResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad grant_type, missing credentials or malformed JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unknown client, wrong secret, revoked account or suspended company (code invalid_client).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "security": []
            }
        },
        "/api/v1/vendors": {
            "get": {
                "tags": [
                    "Vendors"
                ],
                "summary": "List vendors",
                "description": "The company's vendors by name. Archived vendors only with include_archived=true.",
                "operationId": "get_api_v1_vendors",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Only vendors whose name, contact, email or account number contains this.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_archived",
                        "in": "query",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The vendors.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Vendor"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Problem": {
                "title": "Problem (RFC 9457)",
                "required": [
                    "type",
                    "title",
                    "status"
                ],
                "properties": {
                    "type": {
                        "description": "The shared OpenAPI components of the public API (sobocoo-ojl.9): schemas,\nreusable responses, headers and parameters that the controllers reference\nby name. ComponentsDescriber feeds them to the generator, so the document\nat /api/docs.json follows this file and the controller attributes.",
                        "type": "string",
                        "example": "about:blank"
                    },
                    "title": {
                        "type": "string",
                        "example": "Unprocessable Content"
                    },
                    "status": {
                        "type": "integer",
                        "example": 422
                    },
                    "detail": {
                        "type": "string",
                        "example": "The request has invalid fields."
                    },
                    "code": {
                        "description": "Stable machine-readable code (validation_failed, insufficient_stock, rate_limited, invalid_token, forbidden, not_found, ...).",
                        "type": "string",
                        "example": "validation_failed"
                    },
                    "errors": {
                        "description": "On a 422: field name => message.",
                        "type": "object",
                        "example": {
                            "name": "Required."
                        },
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                },
                "type": "object"
            },
            "TokenResponse": {
                "required": [
                    "access_token",
                    "token_type",
                    "expires_in",
                    "scope"
                ],
                "properties": {
                    "access_token": {
                        "description": "The bearer JWT.",
                        "type": "string"
                    },
                    "token_type": {
                        "type": "string",
                        "example": "Bearer"
                    },
                    "expires_in": {
                        "type": "integer",
                        "example": 3600
                    },
                    "scope": {
                        "type": "string",
                        "example": "inventory:read inventory:write"
                    }
                },
                "type": "object"
            },
            "SiteRef": {
                "description": "The site an item (or order) belongs to.",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 3
                    },
                    "name": {
                        "type": "string",
                        "example": "Main"
                    }
                },
                "type": "object"
            },
            "Site": {
                "required": [
                    "id",
                    "name",
                    "default",
                    "for_resale"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 3
                    },
                    "name": {
                        "type": "string",
                        "example": "Main"
                    },
                    "default": {
                        "description": "Where items created without a site_id go.",
                        "type": "boolean"
                    },
                    "for_resale": {
                        "description": "Items here carry a list price and can be sold.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "VendorRef": {
                "description": "The vendor an order is placed with.",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 7
                    },
                    "name": {
                        "type": "string",
                        "example": "Staples"
                    }
                },
                "type": "object"
            },
            "Vendor": {
                "required": [
                    "id",
                    "name",
                    "archived"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 7
                    },
                    "name": {
                        "description": "Unique in the company, case-insensitively.",
                        "type": "string",
                        "example": "Staples"
                    },
                    "contact_name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "email": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "phone": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "website": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "account_number": {
                        "description": "The company's account number with the vendor.",
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "notes": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "archived": {
                        "description": "Archived vendors stay on their orders; new orders cannot use them.",
                        "type": "boolean"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "Item": {
                "required": [
                    "id",
                    "name",
                    "quantity_on_hand"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 42
                    },
                    "site": {
                        "$ref": "#/components/schemas/SiteRef"
                    },
                    "sku": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "PEN-1"
                    },
                    "name": {
                        "type": "string",
                        "example": "Blue pen"
                    },
                    "upc": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "036000291452"
                    },
                    "sobocoo_code": {
                        "description": "Platform-unique 12-character code printed in the QR label.",
                        "type": "string",
                        "example": "ABCDEFGHJKLM"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "unit": {
                        "type": "string",
                        "example": "each"
                    },
                    "unit_cost_cents": {
                        "type": "integer",
                        "example": 120
                    },
                    "price_cents": {
                        "description": "0 when the item does not track a price.",
                        "type": "integer",
                        "example": 250
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    },
                    "for_resale": {
                        "type": "boolean"
                    },
                    "tracks_price": {
                        "description": "Site for resale AND item for resale: Sell is possible.",
                        "type": "boolean"
                    },
                    "quantity_on_hand": {
                        "type": "integer",
                        "example": 12
                    },
                    "reorder_point": {
                        "type": "integer",
                        "example": 5
                    },
                    "low_stock": {
                        "type": "boolean"
                    },
                    "location": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "archived": {
                        "type": "boolean"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "links": {
                        "properties": {
                            "self": {
                                "type": "string",
                                "format": "uri"
                            },
                            "movements": {
                                "type": "string",
                                "format": "uri"
                            },
                            "qr": {
                                "description": "The URL encoded in the item's QR label.",
                                "type": "string",
                                "format": "uri"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "ItemWrite": {
                "description": "Fields of an item. On PATCH every field is optional; unknown fields are a 422.",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Blue pen",
                        "maxLength": 160
                    },
                    "sku": {
                        "description": "Unique within the site.",
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 64
                    },
                    "upc": {
                        "description": "UPC-A / EAN-13 / EAN-8 / GTIN-14 with a valid check digit.",
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 2000
                    },
                    "unit": {
                        "type": "string",
                        "example": "each",
                        "maxLength": 32
                    },
                    "unit_cost_cents": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "price_cents": {
                        "description": "Only when the item tracks a price.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "for_resale": {
                        "type": "boolean"
                    },
                    "reorder_point": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "location": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 120
                    }
                },
                "type": "object"
            },
            "Movement": {
                "required": [
                    "id",
                    "item_id",
                    "type",
                    "quantity",
                    "occurred_at"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "item_id": {
                        "type": "integer"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "receive",
                            "issue",
                            "sale",
                            "adjust"
                        ]
                    },
                    "quantity": {
                        "description": "Signed: receive adds, issue and sale subtract, adjust carries its own sign.",
                        "type": "integer",
                        "example": 10
                    },
                    "unit_cost_cents": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "comp_value_cents": {
                        "description": "A comp (free) receive: what each unit was worth; unit_cost_cents is then 0. Null on other movements.",
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "unit_price_cents": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "buyer": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "note": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "reference": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "PO 1042"
                    },
                    "occurred_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "recorded_by": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "API: POS bridge"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "MovementWrite": {
                "required": [
                    "type",
                    "quantity"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "receive",
                            "issue",
                            "sale",
                            "adjust"
                        ]
                    },
                    "quantity": {
                        "description": "receive/issue/sale: the positive unit count; adjust: the signed delta (non-zero).",
                        "type": "integer",
                        "example": 5
                    },
                    "unit_cost_cents": {
                        "description": "receive only; defaults to the item's unit cost.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "unit_price_cents": {
                        "description": "sale only; defaults to the item's price.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "buyer": {
                        "description": "sale only.",
                        "type": "string",
                        "maxLength": 120
                    },
                    "note": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "reference": {
                        "description": "PO / invoice number; searchable in the audit trail.",
                        "type": "string",
                        "maxLength": 80
                    },
                    "occurred_at": {
                        "description": "Defaults to now.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "allow_negative": {
                        "description": "Let stock go below zero (the ledger then shows the truth; a count can fix it).",
                        "type": "boolean",
                        "default": false
                    },
                    "comp": {
                        "description": "receive only: free (comp) units such as samples, promos or donations. Recorded at unit cost 0 with comp_value_cents; unit_cost_cents is ignored and the item's unit cost does not change.",
                        "type": "boolean",
                        "default": false
                    },
                    "comp_value_cents": {
                        "description": "With comp: true, what each unit is worth; defaults to the item's unit cost.",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "type": "object"
            },
            "OrderListEntry": {
                "required": [
                    "id",
                    "item_id",
                    "quantity",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "item_id": {
                        "type": "integer"
                    },
                    "item_sku": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "item_name": {
                        "type": "string"
                    },
                    "quantity": {
                        "type": "integer"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "open",
                            "ordered",
                            "received",
                            "dismissed"
                        ]
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "web",
                            "scan",
                            "api"
                        ]
                    },
                    "reference": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "purchase_order_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "received_movement_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "PurchaseOrderLine": {
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "item_id": {
                        "type": "integer"
                    },
                    "item_sku": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "item_name": {
                        "type": "string"
                    },
                    "order_list_entry_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "quantity_ordered": {
                        "type": "integer"
                    },
                    "expected_unit_cost_cents": {
                        "type": "integer"
                    },
                    "quantity_received": {
                        "type": "integer"
                    },
                    "quantity_damaged": {
                        "type": "integer"
                    },
                    "quantity_returned": {
                        "type": "integer"
                    },
                    "actual_unit_cost_cents": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "return_reason": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "quantity_comp": {
                        "description": "Comp (free) units promised on top of quantity_ordered.",
                        "type": "integer"
                    },
                    "quantity_comp_received": {
                        "description": "Comp units received into stock (at $0).",
                        "type": "integer"
                    },
                    "quantity_comp_damaged": {
                        "description": "Comp units that arrived damaged (not stocked).",
                        "type": "integer"
                    },
                    "comp_unit_value_cents": {
                        "description": "What one comp unit is worth: the paid unit cost, or the item's cost when that is 0.",
                        "type": "integer"
                    },
                    "outstanding": {
                        "description": "Paid units still expected.",
                        "type": "integer"
                    },
                    "comp_outstanding": {
                        "description": "Comp units still expected.",
                        "type": "integer"
                    },
                    "complete": {
                        "description": "Nothing more expected, paid or comp.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "PurchaseOrderTracking": {
                "description": "A carrier tracking number on a purchase order. Unique within the company.",
                "required": [
                    "id",
                    "number",
                    "carrier"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "number": {
                        "description": "Normalized: uppercase, no spaces or dashes.",
                        "type": "string",
                        "example": "1Z999AA10123456784",
                        "maxLength": 64
                    },
                    "carrier": {
                        "description": "Detected from the number unless given when it was added.",
                        "type": "string",
                        "enum": [
                            "ups",
                            "fedex",
                            "usps",
                            "dhl",
                            "other"
                        ]
                    },
                    "carrier_label": {
                        "type": "string",
                        "example": "UPS"
                    },
                    "tracking_url": {
                        "description": "The carrier's tracking page; null for other.",
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri"
                    },
                    "note": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "added_by": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "received_at": {
                        "description": "When a delivery was recorded from this number.",
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "PurchaseOrderTrackingWrite": {
                "required": [
                    "number"
                ],
                "properties": {
                    "number": {
                        "description": "As typed or scanned; spaces and dashes are removed and letters uppercased (6-64 letters and digits after that).",
                        "type": "string",
                        "example": "1Z 999 AA1 0123 4567 84",
                        "maxLength": 80
                    },
                    "carrier": {
                        "description": "Leave out to detect it from the number.",
                        "type": "string",
                        "enum": [
                            "ups",
                            "fedex",
                            "usps",
                            "dhl",
                            "other"
                        ]
                    },
                    "note": {
                        "type": "string",
                        "maxLength": 200
                    }
                },
                "type": "object"
            },
            "PurchaseOrder": {
                "required": [
                    "id",
                    "number",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "site": {
                        "$ref": "#/components/schemas/SiteRef"
                    },
                    "number": {
                        "type": "string",
                        "example": "PO-1042"
                    },
                    "supplier": {
                        "description": "The linked vendor's current name, the same as vendor.name; null when the order has no vendor. Kept for compatibility; prefer vendor.",
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "vendor": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/VendorRef",
                                "description": "The vendor record, with its current name; null when the order has no supplier."
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "description": "The vendor record, with its current name; null when the order has no supplier."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "open",
                            "partial",
                            "received",
                            "closed"
                        ]
                    },
                    "notes": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "ordered_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "received_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "closed_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "placed_by": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "expected_subtotal_cents": {
                        "type": "integer"
                    },
                    "fees_total_cents": {
                        "type": "integer"
                    },
                    "expected_total_cents": {
                        "type": "integer"
                    },
                    "actual_total_cents": {
                        "type": "integer"
                    },
                    "comp_units": {
                        "description": "Comp (free) units promised across the lines; never in the totals.",
                        "type": "integer"
                    },
                    "comp_value_cents": {
                        "description": "Value of the comp units promised.",
                        "type": "integer"
                    },
                    "comp_received_value_cents": {
                        "description": "Value of the comp units received.",
                        "type": "integer"
                    },
                    "outstanding_units": {
                        "description": "Units still expected, paid and comp.",
                        "type": "integer"
                    },
                    "receivable": {
                        "type": "boolean"
                    },
                    "tracking": {
                        "description": "Carrier tracking numbers, oldest first.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PurchaseOrderTracking"
                        }
                    },
                    "lines": {
                        "description": "Only on the single-order responses.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PurchaseOrderLine"
                        }
                    },
                    "fees": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "amount_cents": {
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Missing, expired or revoked bearer token (WWW-Authenticate: Bearer).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The token lacks the scope, or writes need an active subscription.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "No such record in this company.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            },
            "Validation": {
                "description": "Invalid fields; `errors` maps field to message, `code` says why.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Over the service account's or the company's hourly budget. Retry after `Retry-After` seconds.",
                "headers": {
                    "Retry-After": {
                        "description": "Seconds to wait.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Scope": {
                        "description": "client or company: which window refused.",
                        "schema": {
                            "type": "string"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            }
        },
        "parameters": {
            "from": {
                "name": "from",
                "in": "query",
                "description": "Start of the range (ISO 8601, UTC; inclusive). Default 90 days ago.",
                "schema": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "to": {
                "name": "to",
                "in": "query",
                "description": "End of the range (exclusive). Default tomorrow.",
                "schema": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "limit": {
                "name": "limit",
                "in": "query",
                "description": "Rows per page, 1-100.",
                "schema": {
                    "type": "integer",
                    "default": 50,
                    "maximum": 100,
                    "minimum": 1
                }
            },
            "offset": {
                "name": "offset",
                "in": "query",
                "description": "Rows to skip.",
                "schema": {
                    "type": "integer",
                    "default": 0,
                    "minimum": 0
                }
            }
        },
        "headers": {
            "RateLimit-Limit": {
                "description": "Requests per hour in the tighter window.",
                "schema": {
                    "type": "integer"
                }
            },
            "RateLimit-Remaining": {
                "description": "Requests left in that window.",
                "schema": {
                    "type": "integer"
                }
            },
            "RateLimit-Reset": {
                "description": "Seconds until the window frees up.",
                "schema": {
                    "type": "integer"
                }
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "description": "A token from POST /api/v1/token.",
                "bearerFormat": "JWT",
                "scheme": "bearer"
            },
            "clientCredentials": {
                "type": "oauth2",
                "flows": {
                    "clientCredentials": {
                        "tokenUrl": "/api/v1/token",
                        "scopes": {
                            "inventory:read": "Read items, movements, orders",
                            "inventory:write": "Record movements and counts, create and change items and orders"
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Auth",
            "description": "Token exchange and identity."
        },
        {
            "name": "Sites",
            "description": "Where stock is kept; every item belongs to one site."
        },
        {
            "name": "Items",
            "description": "Inventory items."
        },
        {
            "name": "Stock",
            "description": "Movements and counts: the ledger."
        },
        {
            "name": "Order list",
            "description": "The \"to buy\" list."
        },
        {
            "name": "Purchase orders",
            "description": "Orders placed with suppliers and their receipts."
        },
        {
            "name": "Vendors",
            "description": "Vendors"
        }
    ],
    "servers": [
        {
            "url": "https://tlaa-us.com",
            "description": "This installation"
        }
    ]
}