{"openapi":"3.0.3","info":{"title":"Mat Shelf consumer API","version":"1.0.0","description":"Supplier reference facts and verifiable inventory. Store presentation remains store owned. Cursors are decimal strings; snapshots retain their at revision across pages. See /docs for the consumer contract."},"components":{"securitySchemes":{"storeToken":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/health/live":{"get":{"tags":["Health"],"responses":{"200":{"description":"Default Response"}}}},"/health/ready":{"get":{"tags":["Health"],"responses":{"200":{"description":"Default Response"}}}},"/":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/catalogue":{"get":{"tags":["Catalogue"],"description":"Snapshot: carry at and next.after into subsequent pages, then acknowledge at.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after","required":false},{"schema":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"},"in":"query","name":"at","required":false}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["items","at","next","server_time"],"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","supplier","external_id","sku","aliases","kind","parent_external_ids","lifecycle","source","inventory","revision"],"properties":{"id":{"type":"string","format":"uuid"},"supplier":{"type":"string","enum":["semattor"]},"external_id":{"type":"string"},"sku":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["product","variant"]},"parent_external_ids":{"type":"array","items":{"type":"string"}},"lifecycle":{"type":"string","enum":["active","disabled","missing"]},"source":{"type":"object","additionalProperties":true},"inventory":{"type":"object","additionalProperties":false,"required":["quantity","available","observed_at","expires_at","quality","source_endpoint","freshness"],"properties":{"quantity":{"type":["null","number"]},"available":{"type":["null","boolean"]},"observed_at":{"type":["null","string"],"format":"date-time"},"expires_at":{"type":["null","string"],"format":"date-time"},"quality":{"type":"string","enum":["indexed_stock","salable_stock","unknown"]},"source_endpoint":{"type":["null","string"]},"freshness":{"type":"string","enum":["fresh","stale","unknown"]}}},"revision":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"}}}},"at":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"},"next":{"anyOf":[{"type":"null"},{"type":"object","required":["after","at"],"properties":{"after":{"type":"string","format":"uuid"},"at":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"}}}]},"server_time":{"type":"string","format":"date-time"}}}}}}}}},"/v1/changes":{"get":{"tags":["Catalogue"],"parameters":[{"schema":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$","default":"0"},"in":"query","name":"after","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/entities/{id}":{"get":{"tags":["Catalogue"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["item","server_time"],"properties":{"item":{"type":"object","additionalProperties":false,"required":["id","supplier","external_id","sku","aliases","kind","parent_external_ids","lifecycle","source","inventory","revision"],"properties":{"id":{"type":"string","format":"uuid"},"supplier":{"type":"string","enum":["semattor"]},"external_id":{"type":"string"},"sku":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["product","variant"]},"parent_external_ids":{"type":"array","items":{"type":"string"}},"lifecycle":{"type":"string","enum":["active","disabled","missing"]},"source":{"type":"object","additionalProperties":true},"inventory":{"type":"object","additionalProperties":false,"required":["quantity","available","observed_at","expires_at","quality","source_endpoint","freshness"],"properties":{"quantity":{"type":["null","number"]},"available":{"type":["null","boolean"]},"observed_at":{"type":["null","string"],"format":"date-time"},"expires_at":{"type":["null","string"],"format":"date-time"},"quality":{"type":"string","enum":["indexed_stock","salable_stock","unknown"]},"source_endpoint":{"type":["null","string"]},"freshness":{"type":"string","enum":["fresh","stale","unknown"]}}},"revision":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"}}},"server_time":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/lookup":{"get":{"tags":["Catalogue"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"sku","required":true}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/offers":{"get":{"tags":["Offers"],"description":"Supplier price, content and cost facts per entity, paged by entity ID. Never a retail price instruction.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after","required":false}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/offers/{id}":{"get":{"tags":["Offers"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/status":{"get":{"tags":["Store"],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/inventory/verify":{"get":{"tags":["Inventory"],"description":"Read-only near-checkout evidence. No reservation or permission to replenish. Disabled unless explicitly configured.","parameters":[{"schema":{"type":"array","minItems":1,"maxItems":50,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"in":"query","name":"ids","required":true}],"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items","server_time"],"properties":{"server_time":{"type":"string","format":"date-time"},"items":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["id","lifecycle","reason","inventory"],"properties":{"id":{"type":"string","format":"uuid"},"lifecycle":{"enum":["active","disabled","missing"]},"reason":{"enum":["salable_stock","lifecycle_disabled","lifecycle_missing"]},"inventory":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["external_id","sku","quantity","available","observed_at","expires_at","quality","source_endpoint"],"properties":{"external_id":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"number","minimum":0},"available":{"type":"boolean"},"observed_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"quality":{"enum":["salable_stock"]},"source_endpoint":{"enum":["inventory/get-product-salable-quantity"]}}}]}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/v1/ack":{"post":{"tags":["Store"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string","pattern":"^(0|[1-9][0-9]{0,17})$"},"mode":{"enum":["shadow","stockout","stock","paused"]},"applied":{"type":"integer","minimum":0,"maximum":1000000},"skipped":{"type":"integer","minimum":0,"maximum":1000000},"failed":{"type":"integer","minimum":0,"maximum":1000000},"details":{"type":"array","maxItems":50,"items":{"type":"object","properties":{"sku":{"type":"string","maxLength":200},"reason":{"type":"string","maxLength":500},"local_quantity":{"type":["number","null"]},"source_quantity":{"type":["number","null"]}},"required":["sku","reason"],"additionalProperties":false}}},"required":["cursor","mode","applied","skipped","failed"],"additionalProperties":false}}}},"security":[{"storeToken":[]}],"responses":{"200":{"description":"Default Response"}}}}}}