{"openapi":"3.1.0","info":{"title":"POST /api/v1/bills/received","version":"1.0.0","description":"Create bill in received status"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/bills/received":{"post":{"tags":["bills"],"summary":"Create bill in received status","description":"Create a new bill directly in 'received' status, ready for payment. Creates both the bill AND journal entry when ledger_id is provided.","operationId":"create_bill_received_api_v1_bills_received_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/BillReceivedCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillResponse"}}}},"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"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"detail":"Resource not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BillReceivedCreateRequest":{"properties":{"vendor_id":{"type":"string","title":"Vendor Id","description":"UUID of the vendor this bill is from (required)."},"amount":{"type":"integer","title":"Amount","description":"Bill amount in cents (required)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of what the bill is for."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from the vendor. Auto-generated if not provided."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency for the bill (USD, CAD, AUD, EUR, or GBP). Defaults to business default.","default":"USD"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Bill type: 'recurring' or 'one_time'. Defaults to 'one_time'.","default":"one_time"},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Received On","description":"Date the bill was received (ISO 8601). Defaults to now."},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Due On","description":"Payment due date (ISO 8601)."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of uploaded bill document (PDF/image)."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"UUID of the expense ledger for journal entry creation. If provided, creates journal entry automatically. Ignored when line_items is provided."},"line_items":{"anyOf":[{"items":{"$ref":"#/components/schemas/JournalEntryLineItem"},"type":"array"},{"type":"null"}],"title":"Line Items","description":"Split journal entry lines. Each line specifies a debit account and amount. The credit side is always Accounts Payable. When provided, ledger_id is ignored."},"journal_entry_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Journal Entry Date","description":"Date for the accounting journal entry (ISO 8601 or YYYY-MM-DD). Defaults to received_on if not provided."}},"type":"object","required":["vendor_id","amount"],"title":"BillReceivedCreateRequest","description":"Schema for creating a bill directly in 'received' status.\n\nThis endpoint bypasses the draft stage and creates a bill that's ready\nfor payment. Useful for manually entering bills that have already been received.\n\nWhen ledger_id is provided, this endpoint will also create the associated\njournal entry (debit to expense ledger, credit to accounts payable).\n\nFor split journal entries, provide line_items instead of ledger_id.\nEach line_item specifies a debit account and amount; the credit side\nis always Accounts Payable for the full bill amount.","example":{"amount":56135,"bill_number":"P054","currency":"USD","description":"Purchase Order (P054) issued by Artisan AI LLC","due_on":"2025-03-29T12:00:00Z","journal_entry_date":"2025-02-27T12:00:00Z","ledger_id":"019ab37c-led1-7000-8000-000000000001","received_on":"2025-02-27T12:00:00Z","s3_key":"attachments/019c30bb-dc4c-7e7e-8f9a-123456789abc","type":"one_time","vendor_id":"019ab37c-vend-7000-8000-000000000001"}},"BillResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Bill UUID."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."},"currency":{"type":"string","title":"Currency","description":"Currency for the bill (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"status":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Status","description":"Bill status (see schema description)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Bill description."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from vendor."},"vendor_id":{"type":"string","title":"Vendor Id","description":"Vendor UUID."},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name","description":"Vendor name (resolved)."},"vendor_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Email","description":"Vendor email (resolved)."},"type":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Type","description":"Type: 'recurring' or 'one_time'."},"expected_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Amount","description":"Expected amount in cents."},"expected_paid_on_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expected Paid On Date","description":"Expected payment date."},"total_paid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Paid","description":"Total amount paid so far in cents."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Actual bill amount in cents."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of attached document."},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Received On","description":"Date bill/goods received."},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Due On","description":"Payment due date."},"paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid On","description":"Date fully paid."},"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."},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url","description":"Signed URL to view attached document."},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Payments","description":"List of payments made.","default":[]},"journal_entries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Journal Entries","description":"Associated accounting entries.","default":[]},"recurring_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recurring Template Id","description":"ID of recurring template if this bill was generated from one, or if one was created."},"source_inventory_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Inventory Order Id","description":"Source PO that produced this bill via the PO lifecycle. Non-null means this bill is visible on the Inventory -> Accounts Payable tab."}},"type":"object","required":["id","business_id","status","vendor_id","type","created_at","updated_at"],"title":"BillResponse","description":"Response schema for a bill.\n\nContains all bill details including vendor info, payment status,\nand associated journal entries for accounting.\n\n**Status values:**\n- `draft`: Bill created but not yet approved\n- `forecasted`: Approved, expected to be paid\n- `received`: Bill/goods received, liability recorded\n- `partially_paid`: Some payments made\n- `paid`: Fully paid\n- `canceled`: Cancelled, will not be paid","example":{"amount":250000,"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2024-01-10T10:30:00Z","description":"Monthly office rent - January 2024","due_on":"2024-01-31T00:00:00Z","expected_amount":250000,"id":"019ab37c-bill-7000-8000-000000000001","journal_entries":[],"payments":[],"received_on":"2024-01-15T00:00:00Z","status":"received","type":"recurring","updated_at":"2024-01-15T14:00:00Z","vendor_email":"billing@abcproperty.com","vendor_id":"019ab37c-vend-7000-8000-000000000001","vendor_name":"ABC Property Management"}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JournalEntryLineItem":{"properties":{"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the expense ledger account."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Amount in cents for this line (must be > 0)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description for this line item."}},"type":"object","required":["ledger_id","amount"],"title":"JournalEntryLineItem","description":"A single line item for a split journal entry on bill creation."},"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":[]}]}