Create Invoice | Coperniq API

const url = 'https://api.coperniq.io/v1/invoices';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', '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);
}

{
  "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",
  "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"
      }
    }
  ]
}

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

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

Authentication

x-api-keystring

API Key authentication via header

Request

This endpoint expects an object.

recordIdintegerRequired>=1

Project or account ID

calculationMethodenumRequired

Calculation method

lineItemslist of objectsOptional

Required when calculationMethod is LINE_ITEMS and sections is not provided. Flat array of line items (auto-grouped into one unnamed section).

sectionslist of objectsOptional

Required when calculationMethod is LINE_ITEMS and lineItems is not provided. Grouped line items with named sections. May be combined with lineItems (ungrouped items).

percentagedoubleOptional>=0

Required when calculationMethod is PERCENTAGE.

statusenumOptional

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.

issueDatestringOptionalformat: "date-time"

Issue date (ISO 8601). Optional. Applied only when status is SENT/PARTIALLY_PAID/PAID (required for those); ignored for DRAFT invoices.

dueDatestringOptionalformat: "date-time"

Due date (ISO 8601 datetime string)

descriptionstring or nullOptional

Invoice description

Response

Invoice created successfully

idinteger

Invoice identifier

invoiceNumberinteger

Unique invoice number

statusenum

Invoice status

amountdouble

Total invoice amount

amountPaiddouble

Amount paid

calculationMethodstring

Calculation method (e.g., LINE_ITEMS)

createdAtstringformat: "date-time"

Creation timestamp

updatedAtstringformat: "date-time"

Last update timestamp

descriptionstring or nullOptional

Invoice description

basedOnIdinteger or nullOptional

ID of the record this invoice is based on

basedOnUidinteger or nullOptional

UID of the record this invoice is based on

dueDatestringOptionalformat: "date-time"

Due date

isArchivedbooleanOptional

Whether the invoice is archived

sharedWithPortalbooleanOptional

Whether the invoice is shared with portal

percentagedouble or nullOptional

Percentage if applicable

baseAmountdouble or nullOptional

Base amount if applicable

accountobject or nullOptional

recordobject or nullOptional

lineItemslist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error