{"openapi":"3.1.0","info":{"title":"GET /api/v1/purchase-orders/{po_id}/financing-preview","version":"1.0.0","description":"Preview funding a purchase order from a credit line"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/purchase-orders/{po_id}/financing-preview":{"get":{"tags":["purchase-orders"],"summary":"Preview funding a purchase order from a credit line","description":"For the PO's total (its remaining balance once partly received): the 13-week cash forecast with the PO paid from cash and with it financed, each with its lowest week and balance; and, for each active line the business holds under a per-transaction program, the available credit against the PO amount and an estimated cost of funding it over `term_days` (simple interest at the program's `default_rate_bps` plus the disbursement fee), labelled an estimate. Read-only.","operationId":"get_purchase_order_financing_preview","parameters":[{"name":"po_id","in":"path","required":true,"schema":{"type":"string","title":"Po Id"}},{"name":"term_days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":3650,"minimum":1},{"type":"null"}],"description":"Price the estimate over this term; defaults to each line's term.","title":"Term Days"},"description":"Price the estimate over this term; defaults to each line's term."},{"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_PoFinancingPreviewResponse_"}}}},"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":"get_purchase_order_financing_preview_api_v1_purchase_orders__po_id__financing_preview_get"}}},"components":{"schemas":{"LendingModel":{"type":"string","enum":["per_transaction","cycle_draw"],"title":"LendingModel","description":"What the unit of borrowing is.\n\n* ``per_transaction`` — every posted card transaction originates its\n  own loan with its own term, due date, fee, and daily accrual after\n  the due date. The monthly statement is a presentation wrapper and\n  the moment accrued interest is applied. This is the Tie model\n  (FRD v2 §10.5, D-01).\n* ``cycle_draw`` — settlements accumulate into a monthly cycle that\n  resolves into one draw at close, carrying one term, one due date,\n  and one interest figure. The credit-card model FRD v1 specified.\n\nA program picks one. Lines inherit it, and every engine branch keys\non it, so a second partner on the other model is a row, not a build."},"PoFinancingLineOption":{"properties":{"line_id":{"type":"string","title":"Line Id"},"program_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Id"},"program_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Display Name"},"lending_model":{"$ref":"#/components/schemas/LendingModel"},"status":{"type":"string","title":"Status"},"credit_limit_cents":{"type":"integer","title":"Credit Limit Cents"},"available_credit_cents":{"type":"integer","title":"Available Credit Cents","description":"Headroom today."},"covers_amount":{"type":"boolean","title":"Covers Amount"},"shortfall_cents":{"type":"integer","title":"Shortfall Cents","description":"Amount over the headroom; zero when covered.","default":0},"term_days":{"type":"integer","title":"Term Days","description":"The term the estimate is priced over."},"term_options":{"items":{"type":"integer"},"type":"array","title":"Term Options"},"rate_bps":{"type":"integer","title":"Rate Bps","description":"The program's `default_rate_bps`."},"disbursement_fee_bps":{"type":"integer","title":"Disbursement Fee Bps","description":"The program's `default_disbursement_fee_bps`."},"estimated_interest_cents":{"type":"integer","title":"Estimated Interest Cents"},"estimated_fee_cents":{"type":"integer","title":"Estimated Fee Cents"},"estimated_total_cost_cents":{"type":"integer","title":"Estimated Total Cost Cents"},"estimate_note":{"type":"string","title":"Estimate Note"}},"type":"object","required":["line_id","lending_model","status","credit_limit_cents","available_credit_cents","covers_amount","term_days","term_options","rate_bps","disbursement_fee_bps","estimated_interest_cents","estimated_fee_cents","estimated_total_cost_cents","estimate_note"],"title":"PoFinancingLineOption","description":"One of the business's lines, read against the PO amount."},"PoFinancingPreviewResponse":{"properties":{"po_id":{"type":"string","title":"Po Id"},"po_number":{"type":"string","title":"Po Number"},"po_status":{"type":"string","title":"Po Status"},"amount_cents":{"type":"integer","title":"Amount Cents","description":"What funding this PO means today."},"amount_basis":{"type":"string","enum":["total","remaining_balance"],"title":"Amount Basis"},"expected_pay_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Expected Pay Date"},"in_cash_forecast":{"type":"boolean","title":"In Cash Forecast","description":"Whether the open PO already sits in the baseline forecast."},"forecast_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Forecast Week","description":"Week the PO's payment lands in; 0 is the overdue row."},"term_days":{"type":"integer","title":"Term Days"},"paid_from_cash":{"$ref":"#/components/schemas/PoFinancingScenario"},"financed":{"$ref":"#/components/schemas/PoFinancingScenario"},"lines":{"items":{"$ref":"#/components/schemas/PoFinancingLineOption"},"type":"array","title":"Lines"},"has_eligible_line":{"type":"boolean","title":"Has Eligible Line"}},"type":"object","required":["po_id","po_number","po_status","amount_cents","amount_basis","in_cash_forecast","term_days","paid_from_cash","financed","has_eligible_line"],"title":"PoFinancingPreviewResponse"},"PoFinancingScenario":{"properties":{"label":{"type":"string","enum":["paid_from_cash","financed"],"title":"Label"},"ending_cash_cents":{"type":"integer","title":"Ending Cash Cents"},"lowest_cash_cents":{"type":"integer","title":"Lowest Cash Cents"},"lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lowest Cash Week","description":"1-indexed week with the lowest ending cash."},"lowest_cash_week_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Lowest Cash Week Start"},"weeks":{"items":{"$ref":"#/components/schemas/PoFinancingWeek"},"type":"array","title":"Weeks"}},"type":"object","required":["label","ending_cash_cents","lowest_cash_cents"],"title":"PoFinancingScenario","description":"One 13-week cash forecast run."},"PoFinancingWeek":{"properties":{"week":{"type":"integer","title":"Week"},"start_date":{"type":"string","format":"date","title":"Start Date"},"ending_cash_cents":{"type":"integer","title":"Ending Cash Cents"}},"type":"object","required":["week","start_date","ending_cash_cents"],"title":"PoFinancingWeek"},"SuccessEnvelope_PoFinancingPreviewResponse_":{"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/PoFinancingPreviewResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[PoFinancingPreviewResponse]"},"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":[]}]}