{"openapi":"3.1.0","info":{"title":"GET /api/v1/replenishment/proposals","version":"1.0.0","description":"List replenishment proposals"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/replenishment/proposals":{"get":{"tags":["replenishment"],"summary":"List replenishment proposals","description":"Forecast-driven purchase orders with their funding choice, newest first. Each carries the SKU's weeks of cover and stockout week, the draft PO, the line picked (or cash) with its estimated cost, the 13-week cash trough paid from cash and financed, the repayment weeks and the proposed change that approves it. Lapsed proposals are expired on read.","operationId":"list_replenishment_proposals","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One status or a comma-separated list: proposed, approved, ordered, funded, dismissed, expired.","title":"Status"},"description":"One status or a comma-separated list: proposed, approved, ordered, funded, dismissed, expired."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"Cursor"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Pagination limit","title":"Limit"},"description":"Pagination limit"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Pagination direction: 'next' or 'prev'","default":"next","title":"Direction"},"description":"Pagination direction: 'next' or 'prev'"},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to include total count (expensive - avoid if possible)","default":false,"title":"Include Total Count"},"description":"Whether to include total count (expensive - avoid if possible)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.","title":"Sort By"},"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None."},{"name":"descending","in":"query","required":false,"schema":{"type":"boolean","description":"Sort direction: true for descending (newest/largest first), false for ascending","default":true,"title":"Descending"},"description":"Sort direction: true for descending (newest/largest first), false for ascending"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ReplenishmentProposalListResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_replenishment_proposals_api_v1_replenishment_proposals_get"}}},"components":{"schemas":{"ForecastSnapshot":{"properties":{"on_hand":{"type":"number","title":"On Hand"},"available":{"type":"number","title":"Available"},"weeks_of_cover":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weeks Of Cover","description":"Weeks until available stock runs out on the forecast curve."},"reorder_point":{"type":"number","title":"Reorder Point","description":"The forecast's reorder point."},"order_up_to":{"type":"number","title":"Order Up To"},"suggested_qty":{"type":"integer","title":"Suggested Qty"},"stockout_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stockout Week","description":"1-indexed forecast week the SKU runs out; null if it does not."},"crosses_in_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crosses In Week","description":"1-indexed week the position first crosses the reorder point."},"lead_time_days":{"type":"integer","title":"Lead Time Days"},"lead_weeks":{"type":"integer","title":"Lead Weeks"},"arrival_week":{"type":"integer","title":"Arrival Week","description":"Week the PO's goods land if ordered now."},"avg_weekly_demand":{"type":"number","title":"Avg Weekly Demand"},"weekly_forecast":{"items":{"type":"number"},"type":"array","title":"Weekly Forecast"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"demand_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demand Class"},"unit_cost_cents":{"type":"integer","title":"Unit Cost Cents"}},"type":"object","required":["on_hand","available","reorder_point","order_up_to","suggested_qty","lead_time_days","lead_weeks","arrival_week","avg_weekly_demand","unit_cost_cents"],"title":"ForecastSnapshot","description":"What the demand forecast said when the proposal was built."},"FundingChoice":{"properties":{"line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Id","description":"Null: pay the PO from cash."},"program_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Id"},"program_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Display Name"},"term_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Term Days"},"term_options":{"items":{"type":"integer"},"type":"array","title":"Term Options"},"rate_bps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rate Bps"},"disbursement_fee_bps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Disbursement Fee Bps"},"available_credit_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Available Credit Cents"},"estimated_interest_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Interest Cents"},"estimated_fee_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Fee Cents"},"estimated_cost_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Cost Cents","description":"Interest plus fee over the term; an estimate."},"cash_trough_with_cash":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cash Trough With Cash","description":"Lowest 13-week cash if the PO is paid from cash."},"cash_trough_with_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cash Trough With Cash Week"},"cash_trough_financed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cash Trough Financed","description":"Lowest 13-week cash if the PO is financed."},"cash_trough_financed_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cash Trough Financed Week"},"lines_considered":{"type":"integer","title":"Lines Considered","description":"Eligible lines read; the cheapest with headroom won.","default":0},"no_line_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"No Line Reason","description":"Why no line was chosen: no eligible line, or none with headroom."},"repayment_weeks":{"items":{"$ref":"#/components/schemas/RepaymentWeek"},"type":"array","title":"Repayment Weeks"},"sell_through_weeks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sell Through Weeks","description":"Weeks the lots take to sell through."},"estimate_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimate Note"},"disclosure":{"type":"string","title":"Disclosure","default":"The lender named on the credit line remains lender of record. The cost shown is an estimate priced from the program's rate and fee over the term; what is charged follows the loan's own terms. No money moves when this proposal is approved: a draw happens only when the lender's card is used to pay the vendor."}},"type":"object","title":"FundingChoice","description":"The line picked for this PO, or cash."},"RepaymentWeek":{"properties":{"week":{"type":"integer","title":"Week","description":"1-indexed forecast week."},"start_date":{"type":"string","format":"date","title":"Start Date"},"units":{"type":"number","title":"Units","description":"Units the forecast sells that week."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Those units at the PO's unit cost."}},"type":"object","required":["week","start_date","units","amount_cents"],"title":"RepaymentWeek","description":"One forecast week in which the lots this PO creates sell through."},"ReplenishmentProposalListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReplenishmentProposalResponse"},"type":"array","title":"Items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"has_next":{"type":"boolean","title":"Has Next","default":false},"has_prev":{"type":"boolean","title":"Has Prev","default":false},"proposed_count":{"type":"integer","title":"Proposed Count","description":"Proposals still waiting for a decision.","default":0}},"type":"object","title":"ReplenishmentProposalListResponse"},"ReplenishmentProposalResponse":{"properties":{"id":{"type":"string","title":"Id"},"business_id":{"type":"string","title":"Business Id"},"variant_id":{"type":"string","title":"Variant Id"},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku"},"variant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Name"},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Name"},"vendor_id":{"type":"string","title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name"},"draft_po_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Po Id"},"po_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po Number"},"po_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po Status"},"amount_cents":{"type":"integer","title":"Amount Cents"},"forecast":{"$ref":"#/components/schemas/ForecastSnapshot"},"funding":{"$ref":"#/components/schemas/FundingChoice"},"pending_change_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Change Id"},"pending_change_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Change Status"},"status":{"type":"string","enum":["proposed","approved","ordered","funded","dismissed","expired"],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"decided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Decided At"},"decided_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided By"}},"type":"object","required":["id","business_id","variant_id","vendor_id","amount_cents","forecast","funding","status","created_at","expires_at"],"title":"ReplenishmentProposalResponse"},"SuccessEnvelope_ReplenishmentProposalListResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ReplenishmentProposalListResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ReplenishmentProposalListResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}