> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.coperniq.io/api-reference/invoices/create-invoice/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coperniq.io/_mcp/server. # Create Invoice POST https://api.coperniq.io/v1/invoices Content-Type: application/json Create a new invoice. Required fields: - `recordId`: Project or account ID (the record must exist first) - `calculationMethod`: Must be "LINE_ITEMS" or "PERCENTAGE" Conditionally required: - `lineItems`: Required when `calculationMethod` is "LINE_ITEMS" (at least one item) - `percentage`: Required when `calculationMethod` is "PERCENTAGE" Optional fields: - `issueDate`: ISO 8601 datetime string - `dueDate`: ISO 8601 datetime string - `status`: Initial invoice status (defaults to DRAFT) - `description`: Invoice description Reference: https://docs.coperniq.io/api-reference/invoices/create-invoice ## Authentication - `x-api-key` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects an InvoiceCreate. - `recordId` (integer, required) — Project or account ID - `calculationMethod` (enum, required) — Calculation method - Allowed values: `LINE_ITEMS`, `PERCENTAGE` - `lineItems` (list of InvoiceLineItemCreate, optional) — Required when `calculationMethod` is `LINE_ITEMS` and `sections` is not provided. Flat array of line items (auto-grouped into one unnamed section). - `sections` (list of InvoiceSection, optional) — Required when `calculationMethod` is `LINE_ITEMS` and `lineItems` is not provided. Grouped line items with named sections. May be combined with `lineItems` (ungrouped items). - `percentage` (double, optional) — Required when `calculationMethod` is `PERCENTAGE`. - `status` (enum, optional) — Optional; defaults to DRAFT when omitted. To finalize the invoice, set `SENT`, `PARTIALLY_PAID`, or `PAID` — `issueDate` is then required. Lifecycle statuses (DECLINED, OVERDUE) cannot be set at creation. - Allowed values: `DRAFT`, `SENT`, `PARTIALLY_PAID`, `PAID` - `issueDate` (string, optional) — Issue date (ISO 8601). Optional. Applied only when `status` is SENT/PARTIALLY_PAID/PAID (required for those); ignored for DRAFT invoices. - `dueDate` (string, optional) — Due date (ISO 8601 datetime string) - `description` (string, optional, nullable) — Invoice description ## Response ### 201 Invoice created successfully - `id` (integer, required) — Invoice identifier - `invoiceNumber` (integer, required) — Unique invoice number - `status` (enum, required) — Invoice status - Allowed values: `DRAFT`, `SENT`, `DECLINED`, `PAID`, `PARTIALLY_PAID`, `OVERDUE` - `amount` (double, required) — Total invoice amount - `amountPaid` (double, required) — Amount paid - `calculationMethod` (string, required) — Calculation method (e.g., LINE_ITEMS) - `createdAt` (string, required) — Creation timestamp - `updatedAt` (string, required) — Last update timestamp - `description` (string, optional, nullable) — Invoice description - `basedOnId` (integer, optional, nullable) — ID of the record this invoice is based on - `basedOnUid` (integer, optional, nullable) — UID of the record this invoice is based on - `dueDate` (string, optional) — Due date - `issueDate` (string, optional, nullable) — Issue date when the invoice has been issued - `isArchived` (boolean, optional) — Whether the invoice is archived - `sharedWithPortal` (boolean, optional) — Whether the invoice is shared with portal - `percentage` (double, optional, nullable) — Percentage if applicable - `baseAmount` (double, optional, nullable) — Base amount if applicable - `account` (InvoiceAccount, optional, nullable) - `record` (InvoiceRecord, optional, nullable) - `lineItems` (list of InvoiceLineItem, optional) ## Errors ### 400 Bad Request Error Invalid request - `message` (string, optional) - `code` (enum, optional) - Allowed values: `UNAUTHORIZED` - `field` (string, optional) — Field that caused the validation error (if applicable) ### 401 Unauthorized Error Authentication failed - `message` (string, optional) - `code` (enum, optional) - Allowed values: `UNAUTHORIZED` ## Types ### InvoiceLineItemCreate - `catalogItemId` (integer, required) — Catalog item identifier - `quantity` (integer, required) — Quantity - `unitCost` (double, required) — Cost per unit - `unitPrice` (double, required) — Price per unit (may be negative for discount line items) - `id` (integer, optional, default: 0) — Line item ID (0 for new items) - `description` (string, optional, nullable) — Line item description ### InvoiceSection A named section grouping one or more invoice line items. - `lineItems` (list of InvoiceLineItemCreate, required) — Line items within this section (at least one required) - `id` (integer, optional) — Existing section ID (omit for new sections) - `name` (string, optional, nullable) — Section name (1–500 chars). Omit or pass null for an unnamed section. ### InvoiceAccount - `id` (integer, optional) - `title` (string, optional) ### InvoiceRecord - `id` (integer, optional) - `uid` (integer, optional) - `title` (string, optional) ### InvoiceLineItem - `id` (integer, required) — Line item identifier - `catalogItemId` (integer, required) — Catalog item identifier - `quantity` (integer, required) — Quantity - `unitCost` (double, required) — Cost per unit - `unitPrice` (double, required) — Price per unit - `description` (string, optional, nullable) — Line item description - `catalogItem` (InvoiceLineItemCatalogItem, optional, nullable) ### InvoiceLineItemCatalogItem - `id` (integer, optional) - `name` (string, optional) - `manufacturer` (string, optional, nullable) - `sku` (string, optional, nullable) - `type` (enum, optional) - Allowed values: `PRODUCT`, `SERVICE` ## Examples **Request** ```json { "recordId": 1, "calculationMethod": "LINE_ITEMS" } ``` **Response** ```json { "id": 1, "invoiceNumber": 1, "status": "DRAFT", "amount": 1.1, "amountPaid": 1.1, "calculationMethod": "string", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "description": "string", "basedOnId": 1, "basedOnUid": 1, "dueDate": "2024-01-15T09:30:00Z", "issueDate": "2024-01-15T09:30:00Z", "isArchived": true, "sharedWithPortal": true, "percentage": 1.1, "baseAmount": 1.1, "account": { "id": 1, "title": "string" }, "record": { "id": 1, "uid": 1, "title": "string" }, "lineItems": [ { "id": 1, "catalogItemId": 1, "quantity": 1, "unitCost": 1.1, "unitPrice": 1.1, "description": "string", "catalogItem": { "id": 1, "name": "string", "manufacturer": "string", "sku": "string", "type": "PRODUCT" } } ] } ``` **SDK Code** ```python import requests url = "https://api.coperniq.io/v1/invoices" payload = { "recordId": 1, "calculationMethod": "LINE_ITEMS" } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.coperniq.io/v1/invoices'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"recordId":1,"calculationMethod":"LINE_ITEMS"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.coperniq.io/v1/invoices" payload := strings.NewReader("{\n \"recordId\": 1,\n \"calculationMethod\": \"LINE_ITEMS\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.coperniq.io/v1/invoices") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"recordId\": 1,\n \"calculationMethod\": \"LINE_ITEMS\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.coperniq.io/v1/invoices") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"recordId\": 1,\n \"calculationMethod\": \"LINE_ITEMS\"\n}") .asString(); ``` ```php request('POST', 'https://api.coperniq.io/v1/invoices', [ 'body' => '{ "recordId": 1, "calculationMethod": "LINE_ITEMS" }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.coperniq.io/v1/invoices"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"recordId\": 1,\n \"calculationMethod\": \"LINE_ITEMS\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "recordId": 1, "calculationMethod": "LINE_ITEMS" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.coperniq.io/v1/invoices")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > Official Coperniq API documentation. Build integrations for solar and construction project management — projects, opportunities, work orders, invoices, webhooks, and more.