{"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/SuccessEnvelope_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."},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issue Date","description":"Optional 'Date of issue' to display on the invoice in YYYY-MM-DD format. Use this to backdate an invoice. When set, it replaces the system-generated issue date on the invoice PDF and receipt."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional invoice description or notes."},"fulfillment_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment Location Id","description":"Default warehouse UUID for inventory deductions when the invoice is delivered. Per-line `location_id` overrides this."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Optional UUID of a project (job) to link this invoice to. When the invoice is finalized, its revenue and COGS are attributed to this project for profitability reporting."},"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"}]}},"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."},"fulfillment_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment Location Id","description":"Default warehouse used for inventory deductions."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"UUID of the linked project (job), if any."},"project_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Name","description":"Name of the linked project (resolved), if any."},"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/app__api__v1__schemas__invoices__invoice__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."},"stripe_settlement":{"anyOf":[{"$ref":"#/components/schemas/StripeSettlementInfo"},{"type":"null"}],"description":"Stripe payout and bank deposit linkage for stripe_paid invoices."}},"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","minimum":0.0},{"type":"null"}],"title":"Unit Price","description":"Price per unit in cents. Required for custom items. For variant-linked items this is an OPTIONAL override - if omitted, the current catalog price is used; if provided, the catalog price is ignored for this invoice. The override is snapshotted onto the invoice line item."},"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."},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"Optional warehouse UUID to deduct this line from. Overrides the invoice's `fulfillment_location_id` and the business default. Ignored for custom (non-variant) lines."}},"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 and ``unit_price`` is\noptional - omit to use the catalog price, or provide a value to\noverride it for this invoice. For custom items, ``unit_price`` and\n``description`` are required (amount is auto-calculated).","examples":[{"quantity":2,"variant_id":"019ab37c-var1-7000-8000-000000000001"},{"quantity":2,"unit_price":9999,"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."},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"Warehouse UUID this line was deducted from (if set)."}},"additionalProperties":true,"type":"object","title":"LineItemResponse","description":"Line item in an invoice response.\n\nContains the resolved product/variant information along with pricing."},"StripePayoutBankTransactionSummary":{"properties":{"id":{"type":"string","title":"Id","description":"Bank transaction UUID."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Transaction memo/description."},"datetime":{"type":"string","format":"date","title":"Datetime","description":"The date the deposit occurred."},"amount":{"type":"integer","title":"Amount","description":"Deposit amount in cents (positive)."}},"type":"object","required":["id","datetime","amount"],"title":"StripePayoutBankTransactionSummary","description":"Lightweight bank deposit linked to a Stripe payout."},"StripePayoutInvoiceBreakdownItem":{"properties":{"label":{"type":"string","title":"Label","description":"Customer or invoice label from Stripe."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Charge amount in cents."},"stripe_charge_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Charge Id","description":"Stripe charge ID (ch_…), when available."},"dayzero_invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dayzero Invoice Id","description":"Matched DayZero invoice UUID, when resolved."},"invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Number","description":"Invoice number from metadata or charge description."}},"type":"object","required":["label","amount_cents"],"title":"StripePayoutInvoiceBreakdownItem","description":"One settled charge row included in a Stripe payout."},"StripePayoutSummary":{"properties":{"stripe_payout_id":{"type":"string","title":"Stripe Payout Id","description":"Stripe payout ID (e.g. po_…)."},"status":{"type":"string","title":"Status","description":"Stripe payout status (e.g. paid, pending)."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Net payout amount deposited in cents."},"gross_amount_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gross Amount Cents","description":"Gross charge total in cents before Stripe fees, when computed."},"fee_amount_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fee Amount Cents","description":"Total Stripe fees in cents from balance transactions, when computed."},"stripe_dashboard_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Dashboard Url","description":"Stripe Dashboard URL for this payout, when account context is known."},"payment_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Summary","description":"Human-readable customer/invoice breakdown from balance transactions."},"invoice_breakdown":{"anyOf":[{"items":{"$ref":"#/components/schemas/StripePayoutInvoiceBreakdownItem"},"type":"array"},{"type":"null"}],"title":"Invoice Breakdown","description":"Structured per-charge invoice rows for expandable payout UI."},"arrival_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Arrival Date","description":"Expected bank arrival date from Stripe."},"bank_deposit_match_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bank Deposit Match Id","description":"Matched Plaid bank deposit transaction id, if linked."},"journal_entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Entry Id","description":"Payout journal entry UUID, if created."},"is_matched":{"type":"boolean","title":"Is Matched","description":"True when bank_deposit_match_id is set.","default":false},"bank_transaction":{"anyOf":[{"$ref":"#/components/schemas/StripePayoutBankTransactionSummary"},{"type":"null"}],"description":"Matched bank deposit summary when linked."}},"type":"object","required":["stripe_payout_id","status","amount_cents"],"title":"StripePayoutSummary","description":"Stripe payout metadata for reconciliation audit trails."},"StripeSettlementInfo":{"properties":{"payout":{"$ref":"#/components/schemas/StripePayoutSummary","description":"Stripe payout that settled this invoice's card payment."}},"type":"object","required":["payout"],"title":"StripeSettlementInfo","description":"Stripe settlement chain for a stripe_paid invoice (payout → bank deposit)."},"SuccessEnvelope_InvoiceResponse_":{"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/InvoiceResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[InvoiceResponse]"},"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"},"app__api__v1__schemas__invoices__invoice__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"}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}