{ "openapi": "3.1.0", "info": { "title": "Pharmagistic Partner API", "version": "2026-09-06", "description": "Inventory truth, holds and OMS orders for connected storefronts and partners. Date-versioned: every response carries `X-Pharmagistic-Version: 2026-09-06`; pin it on requests. Beta until three partners are live (breaking changes with 30-day notice); GA = 12-month version support." }, "servers": [ { "url": "https://api.pharmagistic.com", "description": "production" } ], "tags": [ { "name": "ATP" }, { "name": "Orders" }, { "name": "Reserve" } ], "components": { "securitySchemes": { "partnerKey": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer :` — minted in /admin/api-keys." } }, "schemas": {}, "parameters": {} }, "paths": { "/api/v1/check": { "post": { "operationId": "atpCheck", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Available-to-promise for one or more SKUs (no hold)", "description": "Scope `atp.check`. Counts exactly the pools a reserve with the same item would draw from; in-date units only; kits in whole kits.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "brand_code": { "type": "string" } }, "required": [ "sku", "qty" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Per-item availability", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "brand_code": { "type": [ "string", "null" ] }, "requested_qty": { "type": "integer" }, "available_qty": { "type": "integer", "description": "In kits for a multi-formula SKU" }, "atp_qty": { "type": "integer" }, "promised_qty": { "type": "integer" }, "backorder_qty": { "type": "integer" }, "tracks_inventory": { "type": "boolean" }, "known": { "type": "boolean" }, "components": { "type": "array", "items": { "type": "object", "properties": { "formula_id": { "type": "string", "format": "uuid" }, "per_kit": { "type": "integer" }, "available_units": { "type": "integer" }, "atp_units": { "type": "integer" } }, "required": [ "formula_id", "per_kit", "available_units", "atp_units" ] } } }, "required": [ "sku", "brand_code", "requested_qty", "available_qty", "atp_qty", "promised_qty", "backorder_qty", "tracks_inventory", "known" ] } } }, "required": [ "items" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, brand_mismatch}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/reserve": { "post": { "operationId": "atpReserve", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Hold inventory (brand pool first, then shared per access)", "description": "Scope `atp.reserve`. Idempotent by `external_ref` (one active hold per key + reference). Kits are held whole or not at all. 422 `invalid_item` covers an unknown or untracked SKU, an unknown brand code, and an archived/draft formula; 409 `retry` means another hold took the same units at the same moment.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "brand_code": { "type": "string" } }, "required": [ "sku", "qty" ] }, "minItems": 1, "maxItems": 100 }, "ttl_minutes": { "type": "integer", "minimum": 1, "maximum": 525600 }, "external_ref": { "type": "string", "maxLength": 200 } }, "required": [ "items" ] } } } }, "responses": { "201": { "description": "The hold", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reservation_token": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string" }, "idempotent": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "brand_code": { "type": [ "string", "null" ] }, "reserved_qty": { "type": "integer", "description": "In kits: a kit is held whole or not at all" }, "from_brand_pool": { "type": "integer" }, "from_shared_pool": { "type": "integer" }, "fg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "components": { "type": "array", "items": { "type": "object", "properties": { "formula_id": { "type": "string", "format": "uuid" }, "per_kit": { "type": "integer" }, "requested_units": { "type": [ "integer", "null" ], "description": "null on an idempotent replay" }, "reserved_units": { "type": "integer" }, "from_brand_pool": { "type": "integer" }, "from_shared_pool": { "type": "integer" }, "fg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "formula_id", "per_kit", "requested_units", "reserved_units", "from_brand_pool", "from_shared_pool", "fg_ids" ] } } }, "required": [ "sku", "brand_code", "reserved_qty", "from_brand_pool", "from_shared_pool", "fg_ids", "components" ] } } }, "required": [ "reservation_token", "expires_at", "idempotent", "items" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, brand_mismatch}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "error.code ∈ {retry, no_inventory}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "error.code ∈ {invalid_item}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/release": { "post": { "operationId": "atpRelease", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Release a hold", "description": "Scope `atp.release`. Another key's token is a 404, never a 403.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservation_token": { "type": "string", "format": "uuid" } }, "required": [ "reservation_token" ] } } } }, "responses": { "200": { "description": "Released (idempotent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "error.code ∈ {gone}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/consume": { "post": { "operationId": "atpConsume", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Consume a hold WITHOUT creating an OMS order", "description": "Scope `atp.consume` (not granted by default). For a caller that ships the order itself; the units leave the pool under the caller's reference. A hold that became an OMS order is refused.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservation_token": { "type": "string", "format": "uuid" }, "external_ref": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "reservation_token", "external_ref" ] } } } }, "responses": { "200": { "description": "Consumed (idempotent by external_ref)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "consumed_units": { "type": "integer" }, "external_ref": { "type": "string" }, "idempotent": { "type": "boolean" } }, "required": [ "consumed_units", "external_ref", "idempotent" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "error.code ∈ {wrong_state}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/consume/reverse": { "post": { "operationId": "atpReverseConsume", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Give back the units a consume took, when the sale is reversed", "description": "Scope `atp.consume` — the inverse of the authority that took them. Keyed by the `external_ref` the consume was made under, because a consume creates no order here to cancel. For a caller that ships the order itself and has refunded or cancelled it. A reservation that was PLACED as an OMS order is refused with 409: cancel that order instead. Only units still allocated under that reference move — anything shipped, quarantined or destroyed has moved on. THE CALLER OWNS THE \"has it shipped?\" QUESTION: on this configuration the caller buys the label and the OMS never hears about it, so this endpoint cannot check it.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_ref": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "external_ref" ] } } } }, "responses": { "200": { "description": "Returned (idempotent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "returned_units": { "type": "integer" }, "idempotent": { "type": "boolean" } }, "required": [ "returned_units", "idempotent" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "error.code ∈ {not_reversible, not_consumed}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/inventory": { "get": { "operationId": "atpInventory", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "ATP for one SKU by brand plus totals", "description": "Scope `atp.inventory`. `tracks_inventory: false` for a known non-physical SKU (discount, fee); 404 for an unknown one.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "sku", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "brand_code", "in": "query" }, { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "Positions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sku": { "type": "string" }, "tracks_inventory": { "type": "boolean" }, "components": { "type": "array", "items": { "type": "object", "properties": { "formula_id": { "type": "string", "format": "uuid" }, "per_kit": { "type": "integer" }, "on_hand_units": { "type": "integer" }, "reserved_units": { "type": "integer" }, "atp_units": { "type": "integer" } }, "required": [ "formula_id", "per_kit", "on_hand_units", "reserved_units", "atp_units" ] } }, "by_brand": { "type": "array", "items": { "type": "object", "properties": { "brand_code": { "type": [ "string", "null" ] }, "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "atp": { "type": "integer" } }, "required": [ "brand_code", "on_hand", "reserved", "atp" ] } }, "totals": { "type": "object", "properties": { "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "atp": { "type": "integer" } }, "required": [ "on_hand", "reserved", "atp" ] } }, "required": [ "sku", "tracks_inventory", "by_brand", "totals" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, brand_mismatch}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/products": { "get": { "operationId": "catalogProducts", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Every sellable SKU, with availability for this key", "description": "Scope `atp.inventory`. The catalog LISTING: every other endpoint answers about a SKU you already name, so nothing could tell you a product had been ADDED. Untracked SKUs (`tracks_inventory: false`) and physical SKUs with no bill of materials (`sellable: false`) are returned flagged, never omitted — a product list must be able to show that a SKU exists and cannot be reserved. `atp` is in kits, across the pools this key can see.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "The catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "tracks_inventory": { "type": "boolean" }, "sellable": { "type": "boolean" }, "ever_produced": { "type": "boolean" }, "atp": { "type": "integer" } }, "required": [ "sku", "name", "tracks_inventory", "sellable", "ever_produced", "atp" ] } }, "count": { "type": "integer" } }, "required": [ "products", "count" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/orders": { "post": { "operationId": "placeOrder", "tags": [ "Orders" ], "security": [ { "partnerKey": [] } ], "summary": "Place the pickable OMS order from a hold (one transaction)", "description": "Scope `orders.write`. `Idempotency-Key` is required: one key = one order; a replay returns the original with `idempotent: true` and 200. The same key with a different hold is 422 idempotency_mismatch. `shipping_address` is free-form but must serialise under 4 KB.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservation_token": { "type": "string", "format": "uuid" }, "customer": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "consumer" ] }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "full_name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 } }, "required": [ "type", "email" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account" ] }, "account_id": { "type": "string", "format": "uuid" }, "consumer_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "account_id" ] } ] }, "shipping_address": { "type": "object", "additionalProperties": {} }, "notes": { "type": "string", "maxLength": 2000 }, "brand_code": { "type": "string", "maxLength": 40 } }, "required": [ "reservation_token", "customer" ] } } } }, "responses": { "200": { "description": "Replay of an earlier placement", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "order_total": { "type": "number" }, "idempotent": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "description": "Kits" }, "units": { "type": "integer" }, "unit_price": { "type": "number" }, "line_total": { "type": "number" } }, "required": [ "sku", "quantity", "units", "unit_price", "line_total" ] } } }, "required": [ "order_id", "status", "order_total", "idempotent", "lines" ] } }, "required": [ "data" ] } } } }, "201": { "description": "Placed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "order_total": { "type": "number" }, "idempotent": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "description": "Kits" }, "units": { "type": "integer" }, "unit_price": { "type": "number" }, "line_total": { "type": "number" } }, "required": [ "sku", "quantity", "units", "unit_price", "line_total" ] } } }, "required": [ "order_id", "status", "order_total", "idempotent", "lines" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request, idempotency_required}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, reservation_forbidden, brand_mismatch}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {reservation_not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "error.code ∈ {reservation_used, unresolved_stack, kit_incomplete, hold_race}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "error.code ∈ {reservation_gone, reservation_expired, reservation_empty}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "error.code ∈ {invalid_customer, idempotency_mismatch, unknown_brand_code}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/orders/{ref}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "security": [ { "partnerKey": [] } ], "summary": "An order this key placed, by order id or Idempotency-Key", "description": "Scope `orders.read`. Another key's order is a 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "ref", "in": "path" }, { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "order_total": { "type": "number" }, "order_date": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "tracking": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "carrier": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] } }, "required": [ "number", "carrier", "shipped_at" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "units": { "type": "integer" }, "unit_price": { "type": "number" }, "line_total": { "type": "number" }, "fulfilled": { "type": "boolean" } }, "required": [ "sku", "name", "quantity", "units", "unit_price", "line_total", "fulfilled" ] } } }, "required": [ "order_id", "status", "order_total", "order_date", "idempotency_key", "tracking", "lines" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/orders/{ref}/cancel": { "post": { "operationId": "cancelOrder", "tags": [ "Orders" ], "security": [ { "partnerKey": [] } ], "summary": "Cancel an order this key placed, before it is picked", "description": "Scope `orders.write`. Pre-pick only: the allocated units go back to the sellable pool and the order becomes `cancelled`. Once the order is picked, packed or shipped the call is 409 order_not_cancellable and the goods come back through a return authorization instead. Cancelling an already-cancelled order is 200 with `idempotent: true` and releases nothing. Another key's order is a 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "ref", "in": "path" }, { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "released_units": { "type": "integer" }, "idempotent": { "type": "boolean" } }, "required": [ "order_id", "status", "released_units", "idempotent" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, order_forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found, order_not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "error.code ∈ {order_not_cancellable}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/shipments/combine": { "post": { "operationId": "combineShipments", "tags": [ "Orders" ], "security": [ { "partnerKey": [] } ], "summary": "Ship several of this key's orders in one box (combined shipments)", "description": "Scope `orders.write`. Folds the secondary orders into the primary's box: marks each secondary combined and cancels its redundant ShipStation queue order, so only the primary's one label ships the package. Buys no label. `Idempotency-Key` (the console shipment_groups id) is REQUIRED; a replay whose secondaries are already folded into this primary is 200 with `idempotent: true`. Another key's order is a 404; a cross-brand order is 400/403. A ShipStation failure on any secondary is 502 shipstation_error — safe to retry.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "group_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "primary_order_id": { "type": "string", "format": "uuid" }, "secondary_order_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "group_ref", "primary_order_id", "secondary_order_ids" ] } } } }, "responses": { "200": { "description": "Combined (or an idempotent replay)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "combined": { "type": "boolean", "enum": [ true ] }, "group_ref": { "type": "string" }, "primary_order_id": { "type": "string", "format": "uuid" }, "secondaries": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "combined": { "type": "boolean" }, "shipstation": { "type": "string", "enum": [ "cancelled", "sim_skipped", "already_cancelled", "already_labeled", "not_found", "error" ] } }, "required": [ "order_id", "combined", "shipstation" ] } }, "idempotent": { "type": "boolean" } }, "required": [ "combined", "group_ref", "primary_order_id", "secondaries", "idempotent" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "502": { "description": "error.code ∈ {shipstation_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/keys/introspect": { "post": { "operationId": "introspectKey", "tags": [ "Keys" ], "security": [ { "partnerKey": [] } ], "summary": "Is this token a live OMS key, and what may it do?", "description": "Scope `keys.introspect`, PLATFORM keys only (a brand key is 403). The body carries the token a partner presented elsewhere; the answer is `active: false` (200) for an unknown, revoked, expired-brand or mis-bound key, and the key's brand, scopes and sandbox flag when active. Never echoes hashes or rate limits. The console caches the answer for five minutes (decision 14A / 3A).", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 3, "maxLength": 256 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Verdict (active true or false)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "active": { "type": "boolean" }, "key": { "type": "object", "properties": { "key_prefix": { "type": "string" }, "partner_name": { "type": "string" }, "brand_code": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_sandbox": { "type": "boolean" }, "shared_pool_access": { "type": "string", "enum": [ "reserve", "read", "none" ] } }, "required": [ "key_prefix", "partner_name", "brand_code", "scopes", "is_sandbox", "shared_pool_access" ] } }, "required": [ "active" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/shipments": { "get": { "operationId": "listShipments", "tags": [ "Shipments" ], "security": [ { "partnerKey": [] } ], "summary": "This key's brand's ShipStation queue, by modification time", "description": "Scope `shipments.read`, BRAND keys only (a platform key is 403: it names no brand). Pages the brand's mirrored shipments ordered by `greatest(remote_modified_at, updated_at)`; `since` filters on that same time (a label voided or an order cancelled weeks after shipping is returned when it changes, not when it shipped). `shipped_at` is the floor's shipped stamp, else the mirror's modified time for a label-purchased row. `items[].components[]` expands each item to vials, in priority order: the OMS stack BOM, then the brand's SKU alias (by name when the SKU is blank), then the brand's default vial size, else nothing; `items[].resolution` (`bom|alias|default|ignored|unknown`) says which, and `components[].labelled` is false for unlabelled units (e.g. BAC water). `ignored` items (free promos) have no components and must not be counted. The OMS prices nothing. `next_cursor` is opaque; stop when null. Read by the console's 3PL client portal and its nightly fee job.", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "One page, newest change last", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "shipments": { "type": "array", "items": { "type": "object", "properties": { "remote_shipment_id": { "type": "string" }, "shipment_number": { "type": [ "string", "null" ] }, "external_order_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "label_purchased", "cancelled", "on_hold" ] }, "stage": { "type": [ "string", "null" ], "enum": [ "queued", "picking", "picked", "packing", "packed", "labeled", "shipped", "exception", null ] }, "held": { "type": "boolean" }, "hold_reason": { "type": [ "string", "null" ], "enum": [ "inventory_short", "payment_issue", "compliance_review", "customer_request", "qa_review", "other", null ], "description": "Why the floor is holding it (null when not held). The console's reserve gate is not a floor hold; the console knows those itself." }, "exception_reason": { "type": [ "string", "null" ], "description": "Free text from the floor when stage is exception; null otherwise" }, "shipped_at": { "type": [ "string", "null" ] }, "remote_created_at": { "type": [ "string", "null" ] }, "remote_modified_at": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "carrier_code": { "type": [ "string", "null" ] }, "service_code": { "type": [ "string", "null" ] }, "label_cost_cents": { "type": [ "integer", "null" ], "description": "The brand's own postage; informational" }, "item_count": { "type": "integer", "description": "Informational; price from components" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "resolution": { "type": "string", "enum": [ "bom", "alias", "default", "ignored", "unknown" ], "description": "How components were derived: OMS stack BOM; brand SKU/name alias; brand default vial size; alias marked ignore (free promo); nothing matched" }, "components": { "type": "array", "items": { "type": "object", "properties": { "formula_code": { "type": [ "string", "null" ], "description": "OMS formula; null for an alias or brand-default component" }, "vial_size": { "type": [ "string", "null" ], "description": "formulas.vial_size as written (\"10mL clear glass\"); null for alias/default components" }, "vial_ml": { "type": [ "number", "null" ], "description": "Millilitres: parsed from vial_size (BOM), else the alias / brand default; null when unknown or unlabelled" }, "labelled": { "type": "boolean", "description": "True when each vial gets a label (BOM, vial alias, brand default); false for an unlabelled unit such as BAC water" }, "quantity": { "type": "integer", "description": "Vials of this formula in the shipment: per-kit × item quantity" } }, "required": [ "formula_code", "vial_size", "vial_ml", "labelled", "quantity" ] }, "description": "Empty when resolution is ignored or unknown" } }, "required": [ "sku", "name", "quantity", "resolution", "components" ] } } }, "required": [ "remote_shipment_id", "shipment_number", "external_order_id", "status", "stage", "held", "hold_reason", "exception_reason", "shipped_at", "remote_created_at", "remote_modified_at", "tracking_number", "carrier_code", "service_code", "label_cost_cents", "item_count", "items" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "brand_code": { "type": "string" }, "as_of": { "type": "string" } }, "required": [ "shipments", "next_cursor", "brand_code", "as_of" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/inventory/summary": { "get": { "operationId": "inventorySummary", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "What the OMS can ship for this key's brand, one row per formula", "description": "Scope `atp.inventory`, BRAND keys only (a platform key is 403). The brand's OWN units (`own.on_hand/reserved/atp`) are counted; the shared pool is a bucket (`shared`: `in_stock` | `low` (≤ 25 units) | `out` | `no_access` when the brand's `shared_pool_access` is none) — never a count, because the shared pool is the manufacturer's stock. `sold_recently` marks formulas the brand shipped through a stack BOM in the last 90 days. Rows the brand could neither ship nor has sold are omitted. Read by the console's 3PL client portal Inventory tab (increment 4, D13).", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "The summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brand_code": { "type": "string" }, "as_of": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "formula_code": { "type": "string" }, "name": { "type": "string" }, "vial_size": { "type": [ "string", "null" ] }, "own": { "type": "object", "properties": { "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "atp": { "type": "integer" } }, "required": [ "on_hand", "reserved", "atp" ] }, "shared": { "type": "string", "enum": [ "in_stock", "low", "out", "no_access" ] }, "sold_recently": { "type": "boolean" } }, "required": [ "formula_code", "name", "vial_size", "own", "shared", "sold_recently" ] } } }, "required": [ "brand_code", "as_of", "rows" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/receipts": { "get": { "operationId": "listReceipts", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "summary": "Units received into this key's brand's own stock, by batch and day", "description": "Scope `atp.inventory`, BRAND keys only. One row per (day, batch, formula) of finished goods labelled or received into the brand's OWN pool in the last 180 days, with the units received and how many of them remain on the shelf. Shared-pool stock never appears here. Read by the console's 3PL client portal Receiving section (increment 4, D15).", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "responses": { "200": { "description": "The receipts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brand_code": { "type": "string" }, "as_of": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "received_on": { "type": "string", "description": "YYYY-MM-DD: the day the units were labelled to the brand, else created" }, "batch_number": { "type": "string" }, "formula_code": { "type": "string" }, "name": { "type": "string" }, "vial_size": { "type": [ "string", "null" ] }, "product_type": { "type": "string" }, "units": { "type": "integer" }, "remaining": { "type": "integer" } }, "required": [ "received_on", "batch_number", "formula_code", "name", "vial_size", "product_type", "units", "remaining" ] } } }, "required": [ "brand_code", "as_of", "rows" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/reserve-cache": { "post": { "operationId": "pushReserve", "tags": [ "Reserve" ], "security": [ { "partnerKey": [] } ], "summary": "Push the console's prepaid-reserve mirror for one brand", "description": "Scope `reserve.write`, PLATFORM keys only (a brand key is 403). ADR 0017: the OMS stores what the console pushes and never computes a balance or a fee. Replaces the brand's cache row (`balance_cents`, `gate_enabled`, `as_of`) and ALL of its per-shipment fee rows with the payload, atomically. `brand` is a slug or code. When `gate_enabled` and the balance is <= 0 or below a shipment's fee, that queued shipment is not claimable by the pick floor (it stays queued). `blocked` counts the brand's queued rows the gate now blocks.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Brand slug or code" }, "balance_cents": { "type": "integer", "description": "The console's reserve balance for the brand, in cents" }, "gate_enabled": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time", "description": "When the console computed this balance" }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "remote_shipment_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "fee_cents": { "type": "integer", "minimum": 0 } }, "required": [ "remote_shipment_id", "fee_cents" ] }, "maxItems": 2000 } }, "required": [ "brand", "balance_cents", "gate_enabled", "as_of", "shipments" ] } } } }, "responses": { "200": { "description": "Mirror replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brand_code": { "type": "string" }, "balance_cents": { "type": "integer" }, "gate_enabled": { "type": "boolean" }, "as_of": { "type": "string" }, "fee_rows": { "type": "integer", "description": "Per-shipment fee rows now stored for the brand" }, "blocked": { "type": "integer", "description": "Queued worklog rows the gate now blocks from claiming" } }, "required": [ "brand_code", "balance_cents", "gate_enabled", "as_of", "fee_rows", "blocked" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/confirm": { "post": { "operationId": "atpConfirm", "tags": [ "ATP" ], "security": [ { "partnerKey": [] } ], "deprecated": true, "summary": "Legacy: place an OMS order from a hold (use POST /api/v1/orders)", "description": "Scope `atp.confirm`. The same transaction as `/api/v1/orders` with `confirm:` as the idempotency key. Error codes keep their original names (not_found, gone, forbidden). `shipping_address` must serialise under 4 KB.", "parameters": [ { "schema": { "type": "string", "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "example": "2026-09-06" }, "required": false, "description": "Pin the API date. Omit for the current one (2026-09-06); a date newer than the deployment is a 400 unsupported_version.", "name": "X-Pharmagistic-Version", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservation_token": { "type": "string", "format": "uuid" }, "order": { "type": "object", "properties": { "external_ref": { "type": "string", "maxLength": 200 }, "customer": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "consumer" ] }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "full_name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 } }, "required": [ "type", "email" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account" ] }, "account_id": { "type": "string", "format": "uuid" }, "consumer_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "account_id" ] } ] }, "shipping_address": { "type": "object", "additionalProperties": {} }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "customer" ] } }, "required": [ "reservation_token", "order" ] } } } }, "responses": { "200": { "description": "Replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "order_total": { "type": "number" }, "idempotent": { "type": "boolean" }, "items_allocated": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "qty": { "type": "integer" }, "units": { "type": "integer" } }, "required": [ "sku", "qty", "units" ] } } }, "required": [ "order_id", "status", "order_total", "idempotent", "items_allocated" ] } }, "required": [ "data" ] } } } }, "201": { "description": "Placed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "order_total": { "type": "number" }, "idempotent": { "type": "boolean" }, "items_allocated": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "qty": { "type": "integer" }, "units": { "type": "integer" } }, "required": [ "sku", "qty", "units" ] } } }, "required": [ "order_id", "status", "order_total", "idempotent", "items_allocated" ] } }, "required": [ "data" ] } } } }, "400": { "description": "error.code ∈ {invalid_input, unsupported_version, bad_request}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "error.code ∈ {unauthorized}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "error.code ∈ {forbidden, brand_mismatch}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "error.code ∈ {not_found}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "error.code ∈ {reservation_used, kit_incomplete, unresolved_stack, hold_race}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "error.code ∈ {gone}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "error.code ∈ {invalid_customer}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "error.code ∈ {rate_limited}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "error.code ∈ {internal_error}", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {}, "x-aliases": { "/api/v1/atp/{check|reserve|release|consume|inventory|confirm}": "/api/v1/{same} — rewrite kept for one release after 2026-09-06" }, "x-version-header": "X-Pharmagistic-Version" }