{"openapi":"3.1.0","info":{"title":"POST /api/v1/transactions","version":"1.0.0","description":"Create transaction"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/transactions":{"post":{"tags":["transactions"],"summary":"Create transaction","description":"Manually create a transaction record (not synced from bank).","operationId":"create_transaction","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/TransactionCreateRequest"},"example":{"amount":-25000,"datetime":"2024-01-15","description":"Office supplies purchase - Staples","reconciled":false,"source_account_id":"019ab37c-c309-7698-a8d9-14e0409977d8"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_TransactionResponse_"}}}},"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"}}}},"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":"create_transaction_api_v1_transactions_post"}}},"components":{"schemas":{"CategorizedBy":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"rule_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rule Name"},"field_matched":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Matched","description":"The condition field the rule matched on: description, counterparty, amount, transaction_type or bank_account. Null for rows booked before it was recorded."}},"type":"object","required":["rule_id"],"title":"CategorizedBy","description":"The bank rule that chose a transaction's category, from ``meta``."},"CommentResponse":{"properties":{"comment":{"type":"string","maxLength":10000,"minLength":1,"title":"Comment","description":"The comment text content"},"comment_id":{"type":"string","title":"Comment Id","description":"Unique identifier for the comment"},"thread_id":{"type":"string","title":"Thread Id","description":"UUID of the thread this comment belongs to"},"user_id":{"type":"string","title":"User Id","description":"UUID of the user who created the comment"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","description":"Display name of the comment author"},"object_type":{"type":"string","title":"Object Type","description":"Type of object this comment is attached to"},"object_id":{"type":"string","title":"Object Id","description":"UUID of the object this comment is attached to"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the comment was created"}},"type":"object","required":["comment","comment_id","thread_id","user_id","object_type","object_id","created_at"],"title":"CommentResponse","description":"Schema for comment response."},"CounterpartyProvenance":{"properties":{"source":{"type":"string","enum":["manual","alias","matched","registry","naming_rule","raw"],"title":"Source","description":"``manual`` (renamed by hand on this row), ``naming_rule`` (a business naming rule named it), ``alias`` (a saved rename), ``matched`` (named after the business's own customer/vendor: the invoice/bill this payment is linked to, the AR/AP ledger it is booked to, or a customer/vendor the bank text names), ``registry`` (the linked registry entry's canonical name) or ``raw`` (the stored bank counterparty text)."},"alias_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias Id","description":"The saved rename that supplied the name (``alias`` only)."},"alias_key_kind":{"anyOf":[{"type":"string","enum":["registry","name"]},{"type":"null"}],"title":"Alias Key Kind","description":"What that saved rename is keyed on: the registry entry or the raw name (``alias`` only)."},"registry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registry Id","description":"Linked counterparty registry entry, if any."},"registry_canonical_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registry Canonical Name","description":"Canonical name of the linked registry entry, if loaded."},"raw_counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw Counterparty","description":"The counterparty text stored on the row."},"registry_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Registry Confidence","description":"Confidence of the registry link (0-1), if linked."},"counterparty_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty Method","description":"Who wrote the stored text: ``system``, ``pattern``, ``plaid``, ``ai``, ``rule``, ``matched`` or ``user``."},"naming_rule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naming Rule Id","description":"The naming rule that wrote the name (``naming_rule`` only)."},"matched_from":{"anyOf":[{"type":"string","enum":["match","ledger","own_master"]},{"type":"null"}],"title":"Matched From","description":"Which accounting fact named the row (``matched`` only): ``match`` (a linked invoice/bill payment), ``ledger`` (the per-party AR/AP ledger it is booked to) or ``own_master`` (the bank text names one of the business's customers/vendors)."},"matched_party_type":{"anyOf":[{"type":"string","enum":["customer","vendor"]},{"type":"null"}],"title":"Matched Party Type","description":"Kind of master that named the row (``matched`` only)."},"matched_party_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Party Id","description":"Customer or vendor id that named the row (``matched`` only)."}},"type":"object","required":["source"],"title":"CounterpartyProvenance","description":"Where a transaction's displayed counterparty name comes from.\n\nComputed with the same precedence as the displayed name: a name a person\ntyped on the row (``manual``, or ``naming_rule`` when a business naming\nrule wrote it) > a saved rename (``alias``) > the business's own\ncustomer/vendor name taken from its accounting (``matched``) > the linked\nregistry entry's canonical name (``registry``) > the stored bank text\n(``raw``)."},"JournalEntryResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for this journal entry (UUID7)."},"entry_number":{"type":"string","title":"Entry Number","description":"Sequential display number for this journal entry (prefix + sequence)."},"description":{"type":"string","title":"Description","description":"Human-readable description of the transaction."},"currency":{"type":"string","title":"Currency","description":"Currency for the journal entry (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"entry_date":{"type":"string","format":"date","title":"Entry Date","description":"The date this transaction occurred."},"invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Id","description":"UUID of linked invoice, if this entry relates to an invoice."},"inventory_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inventory Order Id","description":"UUID of linked inventory order (PO), if this entry relates to a PO."},"production_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Production Run Id","description":"UUID of the production run whose transfer this entry books."},"reversed_by_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reversed By Id","description":"UUID of the offsetting reversal journal entry, when this entry has been reversed. Set by reverse_journal_entry for idempotency."},"file_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"File Ids","description":"S3 keys of attached supporting documents (PDF, PNG, JPG)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Backend origin: manual, invoice, bill, credit_memo, transaction, stripe, shopify, plaid, ramp, square, system, teal"},"creation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Creation Method","description":"User-facing creation method: ai (system-generated) or manual (user-typed)"},"created_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created Method","description":"How the entry was created: hand_typed (a person keyed the lines), bulk_upload (posted from an uploaded spreadsheet; also source=manual) or system (generated by an integration or workflow)"},"business_id":{"type":"string","title":"Business Id","description":"UUID of the business this entry belongs to."},"line_entries":{"anyOf":[{"items":{"$ref":"#/components/schemas/LineEntryResponse"},"type":"array"},{"type":"null"}],"title":"Line Entries","description":"The debit and credit line entries that make up this journal entry. Will be empty list if not expanded."},"thread":{"anyOf":[{"$ref":"#/components/schemas/JournalEntryThreadResponse"},{"type":"null"}],"description":"Comment thread information if this journal entry has comments. Contains thread_id, comments array, and comment_count."},"credit_memo_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Memo Id","description":"UUID of the linked credit memo, if any."},"vendor_credit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Credit Id","description":"UUID of the linked vendor credit, if any."},"bill_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bill Ids","description":"UUIDs of the bills this entry is linked to."},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"User id that created the entry. Null for entries created before attribution was recorded or by a system process."},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"User id that last updated the entry. Null when never updated by a user."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Advisory notes on a create or update, such as a description that is empty, only an id, or has no month or year. The entry is saved regardless."},"combined_line_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Combined Line Count","description":"On a create with combine_duplicate_lines, how many input lines were merged into another line."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When this journal entry was created."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When this journal entry was last modified."}},"additionalProperties":true,"type":"object","required":["id","entry_number","description","entry_date","business_id"],"title":"JournalEntryResponse","description":"Response schema for a journal entry.\n\nA journal entry is a complete double-entry accounting record consisting of\ntwo or more line entries that must balance (total debits = total credits).","example":{"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","description":"Record sale to customer - Invoice #1234","entry_date":"2024-01-15","id":"019ab37c-0001-7000-8000-000000000001","invoice_id":"019ab37c-e5b3-7c49-96e1-7c3b4d9f0e2b","line_entries":[{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"debit","description":"Accounts Receivable - Customer ABC","entry_date":"2024-01-15","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-c309-7698-a8d9-14e0409977d8","updated_at":"2024-01-15T10:30:00Z"},{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"credit","description":"Sales Revenue","entry_date":"2024-01-15","id":"019ab37c-b2c3-7d4e-f5a6-7b8c9d0e1f2a","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-d4a2-7b38-85f0-6b2a3c8e9f1a","updated_at":"2024-01-15T10:30:00Z"}],"updated_at":"2024-01-15T10:30:00Z"},"examples":[{"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","description":"Record sale to customer - Invoice #1234","entry_date":"2024-01-15","id":"019ab37c-0001-7000-8000-000000000001","invoice_id":"019ab37c-e5b3-7c49-96e1-7c3b4d9f0e2b","line_entries":[{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"debit","description":"Accounts Receivable - Customer ABC","entry_date":"2024-01-15","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-c309-7698-a8d9-14e0409977d8","updated_at":"2024-01-15T10:30:00Z"},{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"credit","description":"Sales Revenue","entry_date":"2024-01-15","id":"019ab37c-b2c3-7d4e-f5a6-7b8c9d0e1f2a","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-d4a2-7b38-85f0-6b2a3c8e9f1a","updated_at":"2024-01-15T10:30:00Z"}],"updated_at":"2024-01-15T10:30:00Z"}]},"JournalEntryThreadResponse":{"properties":{"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thread Id","description":"UUID of the associated comment thread."},"comments":{"items":{"$ref":"#/components/schemas/CommentResponse"},"type":"array","title":"Comments","description":"List of comments in the thread."},"comment_count":{"type":"integer","title":"Comment Count","description":"Total number of comments.","default":0}},"type":"object","title":"JournalEntryThreadResponse","description":"Nested thread information for journal entries.\n\nContains comment thread data when a journal entry has associated comments/discussion."},"LineEntryResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for this line entry (UUID7)."},"amount":{"type":"integer","title":"Amount","description":"Amount in cents (e.g., 15000 = $150.00). Always positive; direction determined by debit_credit."},"currency":{"type":"string","title":"Currency","description":"Currency for the line entry (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"debit_credit":{"type":"string","title":"Debit Credit","description":"Whether this is a 'debit' or 'credit' entry. Debits increase asset/expense accounts; credits increase liability/equity/revenue accounts."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of what this specific line entry represents."},"entry_date":{"type":"string","format":"date","title":"Entry Date","description":"Date of the line entry (typically matches parent journal entry)."},"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the ledger account this entry affects (e.g., Cash, Accounts Receivable)."},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name","description":"Human-readable name of the ledger account (e.g., 'Cash', 'Accounts Receivable')."},"class_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Class Id","description":"Optional Class dimension tag for this line."},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"Optional Location dimension tag for this line."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Optional Project (job-costing) tag for this line."},"counterparty_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty Name","description":"Counterparty of this line when it differs from the transaction's (e.g. one employee's leg of a split payroll debit). Null means the line shares the transaction's counterparty."},"journal_entry_id":{"type":"string","title":"Journal Entry Id","description":"UUID of the parent journal entry this line belongs to."},"business_id":{"type":"string","title":"Business Id","description":"UUID of the business this entry belongs to."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When this line entry was created."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When this line entry was last modified."}},"type":"object","required":["id","amount","debit_credit","entry_date","ledger_id","journal_entry_id","business_id"],"title":"LineEntryResponse","description":"Response schema for a line entry within a journal entry.\n\nEach line entry represents one side of the double-entry accounting record,\neither a debit or credit to a specific ledger account.","example":{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"debit","description":"Accounts Receivable - Customer ABC","entry_date":"2024-01-15","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-c309-7698-a8d9-14e0409977d8","updated_at":"2024-01-15T10:30:00Z"},"examples":[{"amount":150000,"business_id":"019ab37c-0002-7000-8000-000000000002","created_at":"2024-01-15T10:30:00Z","debit_credit":"debit","description":"Accounts Receivable - Customer ABC","entry_date":"2024-01-15","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","journal_entry_id":"019ab37c-0001-7000-8000-000000000001","ledger_id":"019ab37c-c309-7698-a8d9-14e0409977d8","updated_at":"2024-01-15T10:30:00Z"}]},"OpposingLineEntryLedgerInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Ledger UUID."},"name":{"type":"string","title":"Name","description":"Ledger name (e.g., 'Office Supplies', 'Sales Revenue')."},"type":{"type":"string","title":"Type","description":"Ledger type: asset, liability, equity, revenue, expense."},"financial_account_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Financial Account Type","description":"If this ledger is a connected bank/credit-card/prepaid account, the account subtype (e.g. 'bank_account', 'credit_card'). Null for regular category ledgers. Non-null means this opposing entry represents an inter-account movement, not a spend category."},"system_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Key","description":"Immutable system identifier for built-in ledgers (e.g. 'transfers_between_accounts', 'accounts_receivable'). Null for user-created ledgers."}},"type":"object","required":["id","name","type"],"title":"OpposingLineEntryLedgerInfo","description":"Embedded ledger information for opposing line entries."},"OpposingLineEntryResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Line entry UUID."},"amount":{"type":"integer","title":"Amount","description":"Amount in cents (always positive; direction via debit_credit)."},"debit_credit":{"type":"string","title":"Debit Credit","description":"Whether this is a 'debit' or 'credit' entry."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of this line entry."},"class_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Class Id","description":"Class dimension assigned to this line, if any."},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"Location dimension assigned to this line, if any."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Project assigned to this line, if any."},"counterparty_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty Name","description":"Counterparty of this leg when it differs from the transaction's, e.g. the employee on one leg of a split payroll debit. Null means the leg shares the transaction's counterparty."},"ledger":{"$ref":"#/components/schemas/OpposingLineEntryLedgerInfo","description":"The ledger (account) this entry affects."}},"type":"object","required":["id","amount","debit_credit","ledger"],"title":"OpposingLineEntryResponse","description":"Response schema for opposing line entries with ledger details.\n\nOpposing line entries are the counter-entries in a double-entry transaction.\nFor a bank transaction, these represent the category/account the transaction\nwas posted to (e.g., an expense or revenue account).","example":{"amount":15000,"debit_credit":"debit","description":"Office supplies purchase","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","ledger":{"id":"019ab37c-1ed1-7000-8000-000000000001","name":"Office Supplies","type":"expense"}},"examples":[{"amount":15000,"debit_credit":"debit","description":"Office supplies purchase","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","ledger":{"id":"019ab37c-1ed1-7000-8000-000000000001","name":"Office Supplies","type":"expense"}}]},"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."},"fee_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fee Cents","description":"Stripe fee withheld from this charge, when known."},"net_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Net Cents","description":"Amount of this charge that reached the bank."},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email","description":"Customer email on the charge (CSV imports)."},"match_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Source","description":"How the invoice was resolved: number, stripe_invoice, email_amount, or none."}},"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."},"SuccessEnvelope_TransactionResponse_":{"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/TransactionResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[TransactionResponse]"},"TransactionCreateRequest":{"properties":{"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Amount in cents. Positive for deposits/income, negative for withdrawals/expenses."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency code (USD, CAD, AUD, EUR, or GBP). Defaults to business default currency.","default":"USD"},"datetime":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Datetime","description":"Transaction date in ISO 8601 format (YYYY-MM-DD)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the transaction."},"source_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Account Id","description":"UUID of the bank account (ledger) this transaction belongs to."},"reconciled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Reconciled","description":"Whether this transaction has been reconciled with bank statement.","default":false}},"type":"object","title":"TransactionCreateRequest","description":"Request schema for creating a manual transaction.\n\nManual transactions are used for recording transactions that don't come\nfrom a connected bank account (e.g., cash transactions, internal transfers).","example":{"amount":-25000,"datetime":"2024-01-15","description":"Office supplies purchase - Staples","reconciled":false,"source_account_id":"019ab37c-c309-7698-a8d9-14e0409977d8"},"examples":[{"amount":-25000,"datetime":"2024-01-15","description":"Office supplies purchase - Staples","reconciled":false,"source_account_id":"019ab37c-c309-7698-a8d9-14e0409977d8"}]},"TransactionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier (UUID7)."},"amount":{"type":"integer","title":"Amount","description":"Amount in cents. Positive = deposit/income, negative = withdrawal/expense."},"display_amount":{"type":"integer","title":"Display Amount","description":"UI-facing amount in cents using cash-flow convention: negative = outflow/expense, positive = inflow/income. Differs from ``amount`` for credit-card accounts that store Plaid-native signs."},"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 extracted from bank data."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Transaction memo/description (cleaned)."},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Additional metadata (raw Plaid description in raw_plaid_description)."},"attachment_count":{"type":"integer","title":"Attachment Count","description":"Number of receipts / supporting documents attached to this transaction. The entries themselves are in ``meta.attachments``.","default":0},"receipt_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receipt Status","description":"Where this transaction stands on receipts: 'attached', 'exempt' (marked no receipt needed), 'not_required' (the business's receipt policy does not ask for one), 'requested' (the client has an open request) or 'missing'."},"categorization_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Categorization Method","description":"How categorized: 'ai', 'rules', 'similarity', 'transfer_between_accounts', 'uncategorized', 'user', 'historical', or 'global_pattern'; null if uncategorized."},"categorized_by":{"anyOf":[{"$ref":"#/components/schemas/CategorizedBy"},{"type":"null"}],"description":"The bank rule that chose the current category: rule_id, rule_name and field_matched (the condition field it matched on). Null when no rule did. Filter by it with `rule_id`."},"posted_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted Status","description":"Posting status: 'not_posted', 'posted', or 'deleted'."},"review_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Status","description":"Review status: 'unreviewed' or 'reviewed'."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Transaction origin: 'manual', 'plaid', 'bulk_upload', 'xero', 'quickbooks', or 'ramp'. Determines if the transaction can be deleted."},"opposing_line_entry_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Opposing Line Entry Ids","description":"Linked line entry UUIDs for categorization."},"personal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Personal","description":"True if marked as personal (non-business) expense."},"journal_entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Entry Id","description":"Linked journal entry UUID."},"teal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teal Id","description":"External Teal accounting system ID."},"teal_ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teal Ledger Id","description":"Teal ledger ID."},"teal_source_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teal Source Account Id","description":"Teal source account ID."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"Bank account (ledger) UUID."},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name","description":"Bank account (ledger) name for display."},"ledger_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Type","description":"Ledger account type: asset, liability, equity, revenue, or expense."},"account_mask":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Mask","description":"Last 4 digits of the card/account this transaction settled on. From the connected provider account when the ledger is linked; for Ramp rows (which all post to one payable ledger) it is the individual card's last 4. Null when neither is known. Display convention is ``****1234`` (see ``Account.display_name``)."},"card_holder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Holder Name","description":"Employee whose card this charge (or reimbursement) belongs to, as reported by the card program (Ramp). Null for rows from other sources."},"counterparty_provenance":{"anyOf":[{"$ref":"#/components/schemas/CounterpartyProvenance"},{"type":"null"}],"description":"Why ``counterparty`` shows this name: which layer of the name precedence (manual rename > naming rule > saved rename > registry > raw bank text) supplied it."},"business_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Id","description":"Business UUID."},"reconciled":{"type":"boolean","title":"Reconciled","description":"True if reconciled with bank statement.","default":false},"invoice_ids":{"items":{"type":"string"},"type":"array","title":"Invoice Ids","description":"Invoice UUIDs linked via payments (from invoice_payments junction table)."},"bill_ids":{"items":{"type":"string"},"type":"array","title":"Bill Ids","description":"Bill UUIDs linked via payments (from bill_payments junction table)."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Record creation timestamp."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Last update timestamp."},"thread":{"anyOf":[{"$ref":"#/components/schemas/TransactionThreadResponse"},{"type":"null"}],"description":"Comment thread if any discussion exists."},"journal_entry":{"anyOf":[{"$ref":"#/components/schemas/JournalEntryResponse"},{"type":"null"}],"description":"Full journal entry details if categorized."},"opposing_line_entries":{"items":{"$ref":"#/components/schemas/OpposingLineEntryResponse"},"type":"array","title":"Opposing Line Entries","description":"Opposing line entries showing the category/account(s) this transaction was posted to. Empty if uncategorized."},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"True iff the row is in soft-deleted (hidden) state. Hidden rows are excluded from list endpoints and reports; the Restore endpoint can bring them back.","default":false},"can_be_deleted":{"type":"boolean","title":"Can Be Deleted","description":"True iff the caller can delete this transaction. Manual and bulk-uploaded rows are permanently deletable on any engine; Plaid and Xero rows can be soft-deleted (hidden) only on the DayZero local accounting engine; Teal-engine and other-integration rows are not deletable.","default":false},"can_be_restored":{"type":"boolean","title":"Can Be Restored","description":"True iff the caller can restore this previously hidden Plaid or Xero transaction. Always False for other sources and for rows that are not currently in deleted state.","default":false},"deletes_as_soft_hide":{"type":"boolean","title":"Deletes As Soft Hide","description":"True when DELETE will hide (soft-delete) this Plaid or Xero row on the DayZero local engine rather than permanently removing it.","default":false},"stripe_payout":{"anyOf":[{"$ref":"#/components/schemas/StripePayoutSummary"},{"type":"null"}],"description":"Linked Stripe payout when this transaction is a matched bank deposit."}},"additionalProperties":true,"type":"object","required":["id","amount","display_amount","datetime"],"title":"TransactionResponse","description":"Response schema for a bank transaction.\n\nTransactions represent money movement in/out of connected bank accounts.\nEach transaction can be categorized, tagged, and linked to journal entries\nfor proper accounting treatment.","example":{"amount":-15000,"bill_ids":[],"business_id":"019ab37c-b051-7000-8000-000000000001","can_be_deleted":true,"can_be_restored":false,"categorization_method":"rules","counterparty":"Staples","created_at":"2024-01-15T10:30:00Z","datetime":"2024-01-15","description":"Office Supplies","display_amount":-15000,"id":"019ab37c-0001-7000-8000-000000000001","invoice_ids":["019ab37c-1a01-7000-8000-000000000001"],"is_deleted":false,"journal_entry_id":"019ab37c-3e01-7000-8000-000000000001","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","ledger_name":"Chase Checking ****1234","meta":{"category_code":"5943","merchant_name":"Staples","raw_plaid_description":"a1b2c3d4-e5f6-7890-abcd-ef1234567890 | STAPLES | Mon Jan 15 2024 | -150.00 | Purchase | STAPLES | Office Supplies"},"opposing_line_entries":[{"amount":15000,"debit_credit":"debit","description":"Office supplies purchase","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","ledger":{"id":"019ab37c-1ed2-7000-8000-000000000002","name":"Office Supplies","type":"expense"}}],"personal":false,"posted_status":"posted","reconciled":true,"review_status":"reviewed","updated_at":"2024-01-16T09:00:00Z"},"examples":[{"amount":-15000,"bill_ids":[],"business_id":"019ab37c-b051-7000-8000-000000000001","can_be_deleted":true,"can_be_restored":false,"categorization_method":"rules","counterparty":"Staples","created_at":"2024-01-15T10:30:00Z","datetime":"2024-01-15","description":"Office Supplies","display_amount":-15000,"id":"019ab37c-0001-7000-8000-000000000001","invoice_ids":["019ab37c-1a01-7000-8000-000000000001"],"is_deleted":false,"journal_entry_id":"019ab37c-3e01-7000-8000-000000000001","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","ledger_name":"Chase Checking ****1234","meta":{"category_code":"5943","merchant_name":"Staples","raw_plaid_description":"a1b2c3d4-e5f6-7890-abcd-ef1234567890 | STAPLES | Mon Jan 15 2024 | -150.00 | Purchase | STAPLES | Office Supplies"},"opposing_line_entries":[{"amount":15000,"debit_credit":"debit","description":"Office supplies purchase","id":"019ab37c-a1b2-7c3d-e4f5-6a7b8c9d0e1f","ledger":{"id":"019ab37c-1ed2-7000-8000-000000000002","name":"Office Supplies","type":"expense"}}],"personal":false,"posted_status":"posted","reconciled":true,"review_status":"reviewed","updated_at":"2024-01-16T09:00:00Z"}]},"TransactionThreadResponse":{"properties":{"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thread Id","description":"UUID of the associated comment thread."},"comments":{"items":{"$ref":"#/components/schemas/CommentResponse"},"type":"array","title":"Comments","description":"List of comments in the thread."},"comment_count":{"type":"integer","title":"Comment Count","description":"Total number of comments.","default":0}},"type":"object","title":"TransactionThreadResponse","description":"Nested thread information for transactions.\n\nContains comment thread data when a transaction has associated comments/discussion."},"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":[]}]}