--- title: "Create bill" method: POST path: "/v1/platform/businesses/{business_id}/bills/" tags: ["Bills"] --- # Create bill `POST /v1/platform/businesses/{business_id}/bills/` ## Request - Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from) - URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/bills/` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP basic - HTTP bearer - HTTP bearer Create a new bill for a business with line items. Supports idempotency via external_id. ## Path parameters - `business_id` string, required ## Request body - BillCreateAPIRequest: Bill creation serializer. Creates a Bill with line items. - `external_id` string, required: Your unique identifier for this bill (used for idempotency) - `line_items` BillLineItemCreateRequest[], required: Array of line items for this bill (at least one required) - `description` string - `account_identifier` unknown - `product` string - `quantity` number, double, required - `unit_price` integer, required: Unit price in cents - `sales_taxes` object[] - `vendor_id` string, uuid, nullable: UUID of existing vendor (use this OR vendor_external_id, not both) - `vendor_external_id` string: External vendor ID - will auto-create vendor if not found - `bill_number` string: Your internal bill tracking number - `vendor_bill_number` string: Vendor's invoice/bill number from their system - `purchase_order_number` string: Purchase order number if applicable - `memo` string: Description or notes for this bill - `reference_numbers` string[]: Array of additional reference numbers for tracking - `attachment_urls` string[]: Array of URLs to bill documents/PDFs - `bill_date` string, date: Date bill was issued by vendor (ISO date: YYYY-MM-DD) - `received_at` string, date-time: Date/time bill was received (ISO 8601 format) - `due_at` string, date-time: Payment due date/time (ISO 8601 format) - `approved_at` string, date-time, nullable: Date/time bill was approved (triggers journal entry creation) - `currency` 'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD' | '': Bill currency (e.g., GBP, EUR, USD) * `EUR` - Euro * `GBP` - British Pound * `USD` - US Dollar * `SEK` - Swedish Krona * `NOK` - Norwegian Krone * `DKK` - Danish Krone * `ISK` - Icelandic Króna * `MYR` - Malaysian Ringgit * `SGD` - Singapore Dollar - `document` BillDocumentUploadRequest: Bill specific document upload payload. Inherits from BaseFileUploadSerializer pattern for file validation. - `file` string, binary - `document_type` string - `upload_source` string - `metadata` unknown - `tags` unknown ## Response `201` - Bill: Main bill serializer for list/fetch responses, aligned with existing API style - `type` string, required: Always 'BillData' for type discrimination - `id` string, uuid, required - `business_id` string, uuid, required - `external_id` string - `status` string, required: Bill status: received, partially_paid, paid, voided - `terms` string, required: Payment terms (NET_30, NET_60, DUE_ON_RECEIPT, etc.) - `issue_date` string, date, required: Date the bill was issued by vendor (from bill_date) - `received_at` string, date-time, required: Date/time bill was received - `due_at` string, date-time, required: Payment due date/time - `paid_at` string, date-time, required: Full payment completion date/time - `voided_at` string, date-time, required: Void action timestamp - `is_overdue` boolean, required: True if bill is past due date and has outstanding balance - `bill_number` string - `vendor_bill_number` string - `purchase_order_number` string - `memo` string - `reference_numbers` unknown - `attachment_urls` unknown - `metadata` unknown - `currency` string, required - `vendor` Vendor, required: Serializer for vendor objects returned by the vendors list endpoint - `type` string, required: Resource type (always 'VendorData') - `id` string, uuid, required: Unique vendor identifier - `external_id` string: Your unique identifier for this vendor (used for idempotency) - `individual_name` string: Vendor individual name (for sole traders/freelancers) - `company_name` string: Registered company name (for limited companies) - `email` string, email: Primary email address for vendor communications - `mobile_phone` string, required: Mobile phone number (E.164 format, e.g., +44 7700 900123) - `office_phone` string, required: Office phone number (E.164 format, e.g., +44 20 7946 0958) - `address_string` string, required: Full formatted address (read-only, auto-generated) - `memo` string, required: Internal notes or description for this vendor - `status` string, required: Vendor status (ACTIVE, INACTIVE, ARCHIVED, BLOCKED) - `transaction_tags` unknown[], required: List of tags for categorization - unknown - `documents` DocumentFileUrl[], required: All documents linked to this vendor with presigned URLs - `url` string, uri, required: Presigned URL for document download - `expires_in` integer, required: Seconds until URL expires - `document_id` string, uuid, required: Document UUID - `file_name` string, required: Original document filename - `file_size` integer, required: File size in bytes - `mime_type` string, required: MIME type of the document - `line_items` BillLineItem[], required - `id` string, uuid, required - `bill_id` string, uuid, required - `account_identifier` AccountIdentifier, required: Standard account identifier format used across the API. - `type` string: Account identifier type (always 'AccountId') - `id` string, uuid, required: Account UUID - `description` string - `product` string - `currency` string, required - `unit_price` integer, required: Unit price in cents - `quantity` number, float, required: Return quantity as float - `subtotal` integer, required: Subtotal before taxes in cents - `sales_taxes_total` integer, required: Total tax amount in cents - `total_amount` integer, required: Total amount including taxes in cents - `tax_rate` number, float, required: Tax rate as a percentage (e.g., 20.0 for 20%) - `bill_payment_allocations` BillPaymentAllocationSummary[], required: Payment allocations for this bill - `amount_cents` integer, required - `payment_date` string, date, required - `payment_method` string, required - `bill_payment_id` string, uuid, required - `vendor_credit_allocations` VendorCreditAllocationSummary[], required: Vendor credit note allocations for this bill - `amount_cents` integer, required - `applied_at` string, date-time, required - `vendor_credit_id` string, uuid, required - `vendor_credit_number` string - `vendor_refund_allocations` VendorRefundAllocationSummary[], required: Vendor refund allocations for this bill - `vendor_refund_id` string, uuid, required - `reference_number` string - `amount_cents` integer, required - `allocated_at` string, date-time, required - `additional_sales_taxes` AdditionalSalesTax[], required: Additional tax entries not included in line items - `tax_account` unknown - `amount` integer, required: Tax amount in cents - `rate` string, decimal: Tax rate percentage (e.g., 20.00 for 20%) - `name` string: Tax name (e.g., 'VAT', 'GST') - `additional_sales_taxes_total` integer, required: Total additional sales taxes in cents - `subtotal` integer, required: Subtotal amount in cents before taxes - `total_amount` integer, required: Total bill amount in cents including taxes - `outstanding_balance` integer, required: Outstanding balance in cents - `paid_by_bank_payments` integer, required: Amount paid via bank payments in cents (completed only) - `paid_by_credits` integer, required: Amount paid via vendor credit notes in cents - `needs_reconciliation` boolean, required: True if has unreconciled bank payments - `document` DocumentFileUrl, required: Serializer for document file URL with metadata. - `url` string, uri, required: Presigned URL for document download - `expires_in` integer, required: Seconds until URL expires - `document_id` string, uuid, required: Document UUID - `file_name` string, required: Original document filename - `file_size` integer, required: File size in bytes - `mime_type` string, required: MIME type of the document - `created_at` string, date-time, required - `updated_at` string, date-time, required ## Other responses - `400`: Validation errors in request data - `401`: Authentication required - missing or invalid API key - `403`: Permission denied - insufficient privileges - `404`: Resource not found - `409`: Conflict - resource already exists or invalid state transition - `422`: Unprocessable entity - business logic validation failed - `500`: Internal server error --- [API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)