Available Operations

POST /invoices- Create a new invoice
GET /invoices- Get invoices
GET /invoices/{id} - Get invoice by ID
PATCH /invoices/{id} - Update invoice
DELETE /invoices/{id} - Delete invoice
GET /invoices/external-id/{externalId} - Get invoice by external ID

Data Models & Schemas

Invoice Entity

{
  "id": "string",
  "invoiceId": "string",
  "author": "string",
  "contractId": "string",
  "bookingIds": ["string"],
  "updatedAt": "date-time",
  "organization": "string",
  "createdAt": "date-time",
  "isNinjaInvoice": "boolean",
  "clientId": "string",
  "externalId": "string",
  "startDate": "date-time",
  "endDate": "date-time",
  "date": "date",
  "deadline": "date",
  "amount": "number",
  "mediaId": "string",
  "mediaName": "string",
  "status": "enum"
}

Field Descriptions:

id - A unique identifier (UUID) for the invoice record
invoiceId - Invoice number or identifier from the invoicing system
author - A unique identifier (string) representing the user who created the invoice
contractId - A unique identifier (UUID) for the contract associated with this invoice. Links the invoice to a specific contract for tracking and management purposes
bookingIds - An array of unique identifiers (UUIDs) for the bookings associated with this invoice. Allows linking multiple bookings to a single invoice
updatedAt - Timestamp indicating when the invoice was last updated, formatted in ISO 8601 standard (UTC)
organization - A unique identifier (string) for the organization that owns this invoice
createdAt - Timestamp indicating when the invoice was created, formatted in ISO 8601 standard (UTC)
isNinjaInvoice - A boolean value indicating whether this invoice was created from Invoice Ninja system (true) or from the standard system (false)
clientId - A unique identifier (UUID) for the client associated with this invoice. Required field that links the invoice to a specific client
externalId - An optional identifier that connects this invoice record to external systems or databases, facilitating integration with other platforms
startDate - Represents the start date of the billing period for this invoice. Formatted in ISO 8601 standard (UTC)
endDate - Represents the end date of the billing period for this invoice. Formatted in ISO 8601 standard (UTC)
date - The date when the invoice was issued, formatted as a date (YYYY-MM-DD)
deadline - The payment deadline date for the invoice, formatted as a date (YYYY-MM-DD)
amount - A numerical value representing the total amount of the invoice. Maximum value is 100,000,000
mediaId - A unique identifier (UUID) for the associated media file (e.g., PDF of the invoice)
mediaName - The name of the associated media file
status - Current status of the invoice (See available options here: InvoiceStatus)

Enum Fields

InvoiceStatus:

PENDING - Invoice is created but not yet finalized
PAID - Invoice has been paid
UNPAID - Invoice is finalized but not paid

Error Response DTO

Standard error response format.

{
  "status": "number",
  "success": "boolean",
  "message": "string",
  "error": "string"
}

Field Descriptions:

status - HTTP status code (400-503)
success - Boolean indicating the operation failed (false)
message - Human-readable error message
error - Error code identifier