--- title: "Create invoice" method: POST path: "/v1/platform/businesses/{business_id}/invoices/" tags: ["Invoices"] --- # Create invoice `POST /v1/platform/businesses/{business_id}/invoices/` ## 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}/invoices/` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP basic - HTTP bearer - HTTP bearer Create a new invoice for a business with line items and optional payments. Supports optional document upload via multipart field `file` (with optional document_type, upload_source, metadata, tags). JSON-only requests remain supported when no file is provided. ## Path parameters - `business_id` string, uuid, required ## Request body - InvoiceCreateAPIRequest: Invoice creation serializer for API requests Maps API format to internal models and creates invoices with line items - `external_id` string, required: External system identifier for this invoice - `sent_at` string, date-time, required: When the invoice was sent (ISO 8601 format) - `line_items` InvoiceLineItemCreateRequest[], required: Array of line items for this invoice - `external_id` string: External system identifier for this line item - `description` string: Description of the product or service - `account_identifier` unknown - `product` string: Product code or SKU - `quantity` number, double, required: Quantity of items/hours - `unit_price` integer, required: Unit price in cents - `discount_amount` integer: Discount amount in cents - `sales_taxes` TaxLineItemRequest[]: Array of tax line items - `tax_account` unknown - `amount` integer, required: Tax amount in cents - `discount_amount` integer: Discount on tax in cents - `due_at` string, date-time: When payment is due (ISO 8601 format). Defaults to 30 days from sent_at - `voided_at` string, date-time: When the invoice was voided (not used - we use cancelled status) - `invoice_number` string: Invoice number for display. Auto-generated if not provided - `invoice_type` 'invoice' | 'receipt': Type of invoice: invoice or receipt * `invoice` - Invoice * `receipt` - Receipt - `customer_id` string, uuid, nullable: Existing customer ID to assign invoice to - `customer_external_id` string: External customer ID. Will create customer if not found - `memo` string: Invoice description or memo - `additional_discount` integer: Additional invoice-level discount in cents - `additional_sales_taxes` object[]: Array of additional tax objects - `additional_sales_taxes_total` integer: Total additional sales taxes in cents - `tips` integer: Tips amount in cents - `tips_account` unknown - `transaction_tags` string[]: Array of transaction tags for categorization - `metadata` unknown - `document` InvoiceDocumentUploadRequest: Invoice specific document upload payload - `file` string, binary - `document_type` string - `upload_source` string - `metadata` unknown - `tags` unknown ## Response `201` - Invoice: Invoice serializer for API responses All monetary amounts are returned in cents - `type` string, required: Resource type identifier - `id` string, uuid, required: Unique invoice identifier - `business_id` string, uuid, required: Business this invoice belongs to - `external_id` string: External system identifier - `status` 'DRAFT' | 'SENT' | 'PAID' | 'PARTIALLY_PAID' | 'OVERDUE' | 'CANCELLED' | 'REFUNDED', required: Invoice status in uppercase format - `sent_at` string, date-time, required: When the invoice was sent to customer - `due_at` string, date-time, required: When payment is due (ISO timestamp) - `paid_at` string, date-time, required: When the invoice was fully paid - `voided_at` string, date-time, nullable, required: When the invoice was voided (always null - we use cancelled status) - `is_overdue` boolean, required: True if invoice is past due date and has outstanding balance - `invoice_number` string, required: Invoice number for display and reference - `invoice_type` 'invoice' | 'receipt', required: Type of invoice: invoice or receipt * `invoice` - Invoice * `receipt` - Receipt - `currency` string, required: ISO 4217 currency code (e.g., EUR, GBP, USD) - `memo` string: Invoice description or memo - `customer` Customer, required: Main customer serializer for customer API endpoints Returns customer information with comprehensive details Used for both list and detail responses - `type` string, required: Type identifier (always 'CustomerData') - `id` string, uuid, required: Unique identifier for the customer - `external_id` string, required: Your unique identifier for this customer (used for idempotency) - `reference_number` string, required: Customer reference number for invoices and statements - `individual_name` string, required: Individual/contact person name (required if company_name not provided) - `company_name` string, required: Registered company name (required if individual_name not provided) - `display_name` string, required: Display name for the customer (auto-generated from company_name or individual_name) - `email` string, email, required: Primary email address for the customer - `mobile_phone` string, required: Mobile phone number - `office_phone` string, required: Office/landline phone number - `address_line1` string, required: Street address line 1 - `address_line2` string, required: Street address line 2 (building, suite, etc.) - `city` string, required: City or town - `state_county` string, required: State, county, or region - `postal_code` string, required: Postal/ZIP code - `country` string, required: ISO 3166-1 alpha-2 country code - `full_address` string, required: Complete formatted address with all fields - `address_string` string, required: Single-line formatted address - `vat_number` string, required: VAT registration number (for UK: GB followed by 9 digits) - `tax_exempt` boolean, required: Whether customer is exempt from tax/VAT - `status` string, required: Customer status (ACTIVE or ARCHIVED) - `is_active` boolean, required: Whether the customer is active (read-only) - `is_archived` boolean, required: Whether the customer is archived (read-only) - `transaction_tags` unknown[], required: Array of tags for categorization and filtering - unknown - `notes` string, required: Internal notes about the customer - `metadata` unknown, required - `payment_terms_days` integer, required: Number of days for payment terms (e.g., 30 for Net 30) - `credit_limit` integer, required: Maximum credit limit in cents (e.g., 100000 for £1,000) - `credit_limit_cents` integer, required: Maximum credit limit in cents (e.g., 100000 for £1,000) - `outstanding_balance` integer, required: Current outstanding balance in cents (read-only, computed) - `documents` DocumentFileUrl[], required: All documents linked to this customer with presigned URLs (retrieve only, not in list) - `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: Date and time when the customer was created - `updated_at` string, date-time, required: Date and time when the customer was last updated - `archived_at` string, date-time, required: Date and time when the customer was archived (null if active) - `line_items` InvoiceLineItem[], required: Array of invoice line items - `id` string, uuid, required: Unique identifier for the line item - `external_id` string: External system identifier for this line item - `invoice_id` string, uuid, required: Invoice this line item belongs to - `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, required: Description of the product or service - `product` string: Product code or SKU - `unit_price` integer, required: Unit price in cents - `quantity` number, float, required: Quantity of items - `subtotal` integer, required: Subtotal before taxes in cents - `discount_amount` integer, required: Discount amount in cents - `sales_taxes_total` integer, required: Total tax amount in cents - `total_amount` integer, required: Total amount including taxes in cents - `subtotal` integer, required: Subtotal amount in cents before taxes - `additional_discount` integer, required: Additional invoice-level discount in cents - `additional_sales_taxes` AdditionalSalesTax[], required: Additional sales taxes array - `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 - `tips` integer, required: Tips amount in cents - `tips_account` string, nullable, required: Tips account information - `total_amount` integer, required: Total invoice amount in cents including taxes - `outstanding_balance` integer, required: Outstanding balance in cents - `payment_allocations` InvoicePaymentAllocationSummary[], required: Array of payment allocations - `amount_cents` integer, required - `payment_date` string, date, required - `payment_method` string, required - `payment_id` string, uuid, required - `credit_allocations` CustomerCreditAllocationSummary[], required: Array of customer credit note allocations - `amount_cents` integer, required - `applied_at` string, date-time, required - `credit_note_id` string, uuid, required - `reference_number` string - `refund_allocations` RefundAllocationSummary[], required: Array of refund allocations - `refund_id` string, uuid, required - `reference_number` string - `amount_cents` integer, required - `allocated_at` string, date-time, required - `write_offs` WriteOffSummary[], required: Array of write-offs on this invoice - `write_off_id` string, uuid, required - `amount_cents` integer, required - `reason` string, required - `status` string, required - `write_off_at` string, date-time, required - `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 - `imported_at` string, date-time, required: When the invoice was imported/created - `updated_at` string, date-time, required: When the invoice was last updated ## 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)