{"openapi":"3.1.0","info":{"title":"GET /api/v1/invoices","version":"1.0.0","description":"List invoices"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/invoices":{"get":{"tags":["invoices"],"summary":"List invoices","description":"Retrieve invoices with optional filtering by customer, product, or status.","operationId":"get_invoices_api_v1_invoices_get","parameters":[{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by specific invoice UUID","title":"Id"},"description":"Filter by specific invoice UUID"},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by customer UUID","title":"Customer Id"},"description":"Filter by customer UUID"},{"name":"product_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by product UUID","title":"Product Id"},"description":"Filter by product UUID"},{"name":"variant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by variant UUID","title":"Variant Id"},"description":"Filter by variant UUID"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by status. Supports repeated params (?status=open&status=partially-paid) or bracket notation (?status[]=open&status[]=partially-paid).","title":"Status"},"description":"Filter by status. Supports repeated params (?status=open&status=partially-paid) or bracket notation (?status[]=open&status[]=partially-paid)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search invoices by number, description, or customer name (case-insensitive partial match)","title":"Search"},"description":"Search invoices by number, description, or customer name (case-insensitive partial match)"},{"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/InvoiceListResponse"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InvoiceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/InvoiceResponse"},"type":"array","title":"Items","description":"List of items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total number of items (null when not calculated for performance)"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Pagination limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for next page"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor","description":"Cursor for previous page"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous items"}},"type":"object","required":["items","has_next","has_prev"],"title":"InvoiceListResponse","description":"Paginated list of invoices with cursor-based pagination."},"InvoicePaymentResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Payment record UUID."},"invoice_id":{"type":"string","title":"Invoice Id","description":"UUID of the invoice being paid."},"transaction_id":{"type":"string","title":"Transaction Id","description":"UUID of the bank transaction."},"amount":{"type":"integer","title":"Amount","description":"Allocated payment amount in cents."},"currency":{"type":"string","title":"Currency","description":"Currency (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"paid_on":{"type":"string","format":"date-time","title":"Paid On","description":"Effective payment date."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Record creation timestamp."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."},"transaction":{"anyOf":[{"$ref":"#/components/schemas/InvoicePaymentTransactionSummary"},{"type":"null"}],"description":"Linked bank transaction summary. Included when listing payments."}},"type":"object","required":["id","invoice_id","transaction_id","amount","paid_on","created_at","updated_at","business_id"],"title":"InvoicePaymentResponse","description":"Response schema for an invoice payment record.\n\nRepresents a payment made against an invoice, linking to the bank\ntransaction with a specific allocated amount.","example":{"amount":12000,"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2026-02-10T12:00:00Z","currency":"USD","id":"019ab37c-pay1-7000-8000-000000000001","invoice_id":"019ab37c-inv1-7000-8000-000000000001","paid_on":"2026-02-10T00:00:00Z","transaction":{"amount":12000,"counterparty":"Acme Corp","currency":"USD","datetime":"2026-02-10T00:00:00Z","description":"Invoice payment","id":"019ab37c-txn1-7000-8000-000000000001","ledger_id":"019ab37c-led1-7000-8000-000000000001"},"transaction_id":"019ab37c-txn1-7000-8000-000000000001","updated_at":"2026-02-10T12:00:00Z"}},"InvoicePaymentTransactionSummary":{"properties":{"id":{"type":"string","title":"Id","description":"Transaction UUID."},"amount":{"type":"integer","title":"Amount","description":"Transaction amount in cents. Positive = deposit, negative = withdrawal."},"currency":{"type":"string","title":"Currency","description":"Currency code (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"datetime":{"type":"string","format":"date","title":"Datetime","description":"The date the transaction occurred."},"counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty","description":"Clean counterparty/merchant name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Transaction memo/description."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"Bank account (ledger) UUID."}},"type":"object","required":["id","amount","datetime"],"title":"InvoicePaymentTransactionSummary","description":"Lightweight transaction summary embedded in invoice payment responses.\n\nContains the key fields needed to display the linked bank transaction\nwithout pulling the full TransactionResponse (journal entries, threads, etc.)."},"InvoiceResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Invoice UUID."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp."},"status":{"type":"string","title":"Status","description":"Status: draft, open, partially_paid, manual_paid, stripe_paid, void."},"currency":{"type":"string","title":"Currency","description":"Currency for the invoice (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"stripe_invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Invoice Id","description":"Stripe invoice ID if synced."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total amount in cents."},"total_paid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Paid","description":"Running total of payments received in cents."},"balance_due":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Balance Due","description":"Remaining balance in cents (total - total_paid)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Invoice description/notes."},"customer_id":{"type":"string","title":"Customer Id","description":"Customer UUID."},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name","description":"Customer name (resolved)."},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email","description":"Customer email (resolved)."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date","description":"Due date (YYYY-MM-DD)."},"line_items":{"anyOf":[{"items":{"$ref":"#/components/schemas/LineItemResponse"},"type":"array"},{"type":"null"}],"title":"Line Items","description":"Invoice line items."},"pdf_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Url","description":"URL to download invoice PDF."},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Invoice number (assigned on finalize)."},"delivered":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Delivered","description":"Whether invoice was delivered."},"delivered_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered On","description":"Delivery timestamp."},"hosted_invoice_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hosted Invoice Url","description":"URL for customer payment portal."},"paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid On","description":"Payment timestamp."},"journal_entries":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Journal Entries","description":"Associated accounting journal entries.","default":[]},"payments":{"anyOf":[{"items":{"$ref":"#/components/schemas/InvoicePaymentResponse"},"type":"array"},{"type":"null"}],"title":"Payments","description":"Payment records linking bank transactions to this invoice.","default":[]},"recurring_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recurring Template Id","description":"ID of recurring template if invoice was generated from one, or if one was created."}},"additionalProperties":true,"type":"object","required":["id","business_id","created_at","updated_at","status","customer_id"],"title":"InvoiceResponse","description":"Response schema for an invoice.\n\nContains all invoice details including customer info, line items,\npayment status, and associated accounting entries.","example":{"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2024-01-15T10:30:00Z","customer_email":"billing@acme.com","customer_id":"019ab37c-cust-7000-8000-000000000001","customer_name":"Acme Corporation","delivered":true,"delivered_on":"2024-01-16T09:00:00Z","description":"January services","due_date":"2024-02-15","id":"019ab37c-inv1-7000-8000-000000000001","line_items":[{"amount":75000,"description":"Widget Pro","quantity":3,"unit_price":25000,"variant_id":"019ab37c-var1-7000-8000-000000000001","variant_name":"Widget Pro - Large"},{"amount":2500,"description":"Rush delivery fee","quantity":1,"variant_id":"custom"}],"number":"INV-2024-0001","status":"pending","total":77500,"updated_at":"2024-01-15T10:30:00Z"}},"LineItemResponse":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Product variant UUID or 'custom'."},"quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quantity","description":"Quantity ordered."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Line item description."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Total line amount in cents."},"variant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Name","description":"Product variant name (resolved)."},"unit_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unit Price","description":"Price per unit in cents."}},"additionalProperties":true,"type":"object","title":"LineItemResponse","description":"Line item in an invoice response.\n\nContains the resolved product/variant information along with pricing."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}