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,
  "uid": 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",
  "type": "INVOICE",
  "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

uidinteger

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 null

Invoice description

typeenum or null

Invoice type

basedOnIdinteger or null

ID of the record this invoice is based on

basedOnUidinteger or null

UID of the record this invoice is based on

dueDatestringformat: "date-time"

Due date

isArchivedboolean

Whether the invoice is archived

sharedWithPortalboolean

Whether the invoice is shared with portal

percentagedouble or null

Percentage if applicable

baseAmountdouble or null

Base amount if applicable

accountobject or null

recordobject or null

lineItemslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error