{"openapi":"3.1.0","info":{"title":"POST /api/v1/invoices","version":"1.0.0","description":"Create invoice"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/invoices":{"post":{"tags":["invoices"],"summary":"Create invoice","description":"Create a new invoice for a customer. Optionally include 'recurring' config to also create a recurring template.","operationId":"create_invoice_api_v1_invoices_post","parameters":[{"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"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"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"},"InvoiceCreateRequest":{"properties":{"customer_id":{"type":"string","title":"Customer Id","description":"UUID of the customer to invoice."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency for the invoice (USD, CAD, AUD, EUR, or GBP). Defaults to business default.","default":"USD"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemRequest"},"type":"array","minItems":1,"title":"Line Items","description":"Line items (at least one required). Can be variant-linked or custom."},"due_date":{"type":"string","title":"Due Date","description":"Payment due date in YYYY-MM-DD format."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional invoice description or notes."},"recurring":{"anyOf":[{"$ref":"#/components/schemas/InvoiceRecurringConfig"},{"type":"null"}],"description":"If provided, creates a recurring template for this invoice."}},"additionalProperties":true,"type":"object","required":["customer_id","line_items","due_date"],"title":"InvoiceCreateRequest","description":"Request schema for creating a new invoice.\n\nAn invoice represents a bill sent to a customer for goods or services.\nIt contains one or more line items and tracks payment status through\nits lifecycle: draft → pending → paid (or void).","example":{"customer_id":"019ab37c-cust-7000-8000-000000000001","description":"January services","due_date":"2024-02-15","line_items":[{"quantity":3,"variant_id":"019ab37c-var1-7000-8000-000000000001"},{"amount":2500,"description":"Rush delivery fee","variant_id":"custom"}]}},"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.)."},"InvoiceRecurringConfig":{"properties":{"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","annually"],"title":"Frequency","description":"How often to generate invoices."},"start_date":{"type":"string","format":"date","title":"Start Date","description":"When to start generating invoices (first occurrence)."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name for the recurring template. Defaults to invoice description."},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"Stop generating after this date (null = indefinite). If both end_date and max_occurrences are set, whichever is reached first stops generation."},"day_of_month":{"anyOf":[{"type":"integer","maximum":31.0,"minimum":1.0},{"type":"null"}],"title":"Day Of Month","description":"Day of month (1-31). Only applies to monthly/quarterly/annually frequencies; ignored for daily/weekly/biweekly. If the day doesn't exist in a month (e.g., 31 in February), generates on the last day instead. If omitted, uses the day from start_date."},"day_of_week":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":0.0},{"type":"null"}],"title":"Day Of Week","description":"Day of week (0=Monday, 6=Sunday). Only applies to weekly/biweekly frequencies; ignored for other frequencies. If omitted, uses the weekday from start_date."},"days_until_due":{"type":"integer","maximum":365.0,"minimum":0.0,"title":"Days Until Due","description":"Days from generation until due date.","default":30},"max_occurrences":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Occurrences","description":"Stop after generating this many invoices (null = unlimited). If both end_date and max_occurrences are set, whichever is reached first stops generation."}},"type":"object","required":["frequency","start_date"],"title":"InvoiceRecurringConfig","description":"Recurring configuration that can be embedded in invoice create/update requests.","example":{"day_of_month":1,"days_until_due":30,"frequency":"monthly","start_date":"2026-02-01"}},"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"}},"LineItemRequest":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"UUID of product variant. Omit or use 'custom' for manual line items."},"quantity":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Quantity","description":"Quantity ordered. Defaults to 1 for custom items."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Line item description (required for custom items)."},"unit_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unit Price","description":"Price per unit in cents. Required for custom items, auto-resolved for variants."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Total amount in cents. Deprecated for custom items - use unit_price instead. For backward compatibility, if unit_price is not set, amount is treated as unit_price."}},"additionalProperties":true,"type":"object","title":"LineItemRequest","description":"Line item for invoice requests.\n\nLine items can be linked to product variants or be custom items.\nFor variant-linked items, quantity is required. For custom items,\nunit_price and description are required (amount is auto-calculated).","examples":[{"quantity":2,"variant_id":"019ab37c-var1-7000-8000-000000000001"},{"description":"Consulting services","quantity":5,"unit_price":15000,"variant_id":"custom"}]},"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":[]}]}