{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/lines/{credit_line_id}/credit-balance","version":"1.0.0","description":"Where a line's credit balance came from"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/lines/{credit_line_id}/credit-balance":{"get":{"tags":["credit"],"summary":"Where a line's credit balance came from","description":"The line's carried-forward credit and the entries it is made of, newest first: each entry's `source` (`overpayment`, `refund`, `dispute`, `opening`) and `source_reference`, `amount_cents`, `consumed_cents`, `withdrawn_cents`, `remaining_cents`, `status`, and the loans that consumed it (`consumptions`). The sum of `remaining_cents` (`entries_remaining_cents`) equals `credit_balance_cents` less `unattributed_cents`, which is non-zero only on a line whose credit predates entries and has not moved since. Filter with `status` (comma-separated: `open`, `consumed`, `withdrawn`).","operationId":"get_credit_line_credit_balance","parameters":[{"name":"credit_line_id","in":"path","required":true,"schema":{"type":"string","title":"Credit Line Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated entry statuses: open, consumed, withdrawn.","title":"Status"},"description":"Comma-separated entry statuses: open, consumed, withdrawn."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Entries per page (1-500).","default":50,"title":"Limit"},"description":"Entries per page (1-500)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page.","title":"Cursor"},"description":"`next_cursor` from the previous page."},{"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_CreditBalanceResponse_"}}}},"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_credit_line_credit_balance_api_v1_credit_lines__credit_line_id__credit_balance_get"}}},"components":{"schemas":{"CreditBalanceConsumptionResponse":{"properties":{"loan_id":{"type":"string","title":"Loan Id","description":"The loan that consumed the credit."},"external_settlement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Settlement Id","description":"The issuer transaction id of that loan."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"What the loan consumed at origination."},"on":{"type":"string","format":"date","title":"On","description":"The loan's transaction date, when it consumed it."},"withdrawn_cents":{"type":"integer","title":"Withdrawn Cents","description":"What was later taken back from the loan because the entry's source was withdrawn (the loan owes it again).","default":0},"withdrawn_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Withdrawn On","description":"When it was last taken back; null if never."}},"type":"object","required":["loan_id","amount_cents","on"],"title":"CreditBalanceConsumptionResponse","description":"One loan that consumed part of an entry."},"CreditBalanceEntryResponse":{"properties":{"id":{"type":"string","title":"Id","description":"The entry id."},"source":{"type":"string","enum":["overpayment","refund","dispute","opening"],"title":"Source","description":"overpayment (a payment left money over), refund (a refund larger than its loan owed), dispute (a dispute won by the merchant or a void reversed money already paid), or opening (credit the line held before DayZero recorded where credit comes from)."},"source_payment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Payment Id","description":"The payment, for an overpayment."},"source_settlement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Settlement Id","description":"The refund settlement, for a refund."},"source_dispute_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Dispute Id","description":"The dispute, for a dispute."},"source_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Reference","description":"Your reference for the source: the external payment id, the refund's external settlement id, or the issuer's dispute id (the dispute id when the issuer gave none). Null for opening."},"created_on":{"type":"string","format":"date","title":"Created On","description":"The business date the credit arose. Loans consume oldest first."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Credit the source created, in total."},"consumed_cents":{"type":"integer","title":"Consumed Cents","description":"What loans hold of it now."},"withdrawn_cents":{"type":"integer","title":"Withdrawn Cents","description":"Taken back because the source was not real or shrank: the unconsumed part withdrawn plus what was taken back from loans."},"remaining_cents":{"type":"integer","title":"Remaining Cents","description":"Still available to the next loan: amount - consumed - withdrawn."},"status":{"type":"string","enum":["open","consumed","withdrawn"],"title":"Status","description":"open while any remains, else consumed or withdrawn."},"consumptions":{"items":{"$ref":"#/components/schemas/CreditBalanceConsumptionResponse"},"type":"array","title":"Consumptions","description":"Each loan that consumed part of it."}},"type":"object","required":["id","source","created_on","amount_cents","consumed_cents","withdrawn_cents","remaining_cents","status"],"title":"CreditBalanceEntryResponse","description":"One deposit of credit: its source, and where it went."},"CreditBalanceResponse":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass back as `cursor` for the next page. Null on the last."},"has_next":{"type":"boolean","title":"Has Next","description":"Another page follows. Looked up one row past the page, so a full last page is not reported as more.","default":false},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The page size the list was read with."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Row count; present only with `include_total_count=true`."},"credit_line_id":{"type":"string","title":"Credit Line Id","description":"The line."},"credit_balance_cents":{"type":"integer","title":"Credit Balance Cents","description":"The line's credit balance, as on the dashboard."},"entries_remaining_cents":{"type":"integer","title":"Entries Remaining Cents","description":"The sum of every entry's remaining_cents: the balance less `unattributed_cents`."},"unattributed_cents":{"type":"integer","title":"Unattributed Cents","description":"Balance no entry accounts for. Non-zero only on a line that held credit before entries were recorded and has not been touched since; it gets an opening entry the next time its credit moves."},"open_entry_count":{"type":"integer","title":"Open Entry Count","description":"Entries with credit remaining."},"items":{"items":{"$ref":"#/components/schemas/CreditBalanceEntryResponse"},"type":"array","title":"Items","description":"Entries, newest first."}},"type":"object","required":["credit_line_id","credit_balance_cents","entries_remaining_cents","unattributed_cents","open_entry_count"],"title":"CreditBalanceResponse","description":"A line's carried-forward credit and the entries it is made of."},"SuccessEnvelope_CreditBalanceResponse_":{"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/CreditBalanceResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[CreditBalanceResponse]"},"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":[]}]}