Invoices

Invoices represent a formal statement issued by a seller to a buyer, which indicates the quantities and costs of the products or services provided by the vendor.

Schema

Invoice

Name	Type	Description	Example
id	ID	Unique identifier for invoices	"ckmnpybisiy5x08abky4g2d1f"
createdAt	DateTime	When this invoice was created	"2021-03-24 17:26:46.983Z"
createdById	ID	ID of the user who created this invoice	"ckmnpybisiy5x08abky4g2d1f"
createdBy	User	User who created the invoice	See User docs
updatedAt	DateTime	When this invoice was updated	"2021-03-24 17:26:46.983Z"
deletedAt	DateTime?	When this invoice was deleted	"2021-03-24 17:26:46.983Z"
title	string?	Title of the invoice	"Invoice 1234"
approvedAt	DateTime?	When this invoice was approved	"2021-03-24 17:26:46.983Z"
approvedById	ID?	ID of the user who approved this invoice	"ckmnpybisiy5x08abky4g2d1f"
approvedBy	User?	User who approved the invoice	See User docs
category	InvoiceCategory?	Category of the invoice	miscellaneous
dueDate	DateTime?	When a payment for the invoice is due	"2021-03-24 17:26:46.983Z"
invoiceDate	DateTime?	When this invoices was issued by the vendor	"2021-03-24 17:26:46.983Z"
exceptions	string[]	Array indicating which fields in the invoice have exceptions or discrepancies	["totalDue","subtotal"]
flaggedAt	DateTime?	When this invoice was flagged	"2021-03-24 17:26:46.983Z"
flaggedById	ID?	ID of the user who flagged this invoice	"ckmnpybisiy5x08abky4g2d1f"
flaggedBy	User?	User who flagged the invoice	See User docs
flagMessage	string?	User's description of the flagged issue with this invoice	"Urgent!!"
invoiceNumber	string?	User-defined value to identify this invoice	"Invoice-1234"
paidAt	DateTime?	When this invoice was paid	"2021-03-24 17:26:46.983Z"
paidById	ID?	ID of the user who made a payment for this invoice	"ckmnpybisiy5x08abky4g2d1f"
payments	float?	The amount of payments on the invoice	12.55
rejectedAt	DateTime?	When this invoice was rejected	"2021-03-24 17:26:46.983Z"
rejectedById	ID?	ID of the user who rejected this invoice	"ckmnpybisiy5x08abky4g2d1f"
rejectedReason	string?	Reason provided by the user for rejecting the invoice	"Created accidentally"
salesperson	string?	Salesperson associated with this invoice	"Mike R."
shipDate	DateTime?	Date when the products stated in the invoice were shipped	"2021-03-24 17:26:46.983Z"
shippingCostFloat	float?	The cost of shipping	10.00
shipVia	string?	Method of shipment	"Freight"
state	InvoiceState	The current state of the invoice	APPROVED
integrationState	InvoiceIntegrationState	The synchronization status between the invoice and the integrated system	LINKED
integrationMessage	string?	A message about the status of the integration's sync	"GL Code is required for item 1"
subtotal	float?	Subtotal of the invoice before addition of other costs such as taxes	6.13
tax	float?	The amount of tax on the invoice	5.00
terms	string?	Terms of payment for the invoice	"CWO"
totalDue	float?	The total amount due	55.55
voidedAt	DateTime?	When this invoice was voided	"2021-03-24 17:26:46.983Z"
voidedById	ID?	ID of the user who voided the invoice	"ckmnpybisiy5x08abky4g2d1f"
voidedBy	User?	User who voided the invoice	See User docs
creditMemos	CreditMemo[]	Credit memos associated with the invoice	See CreditMemo Docs
invoiceItems	InvoiceItem[]	Items listed in the invoice	See Invoice Item Docs
job	Job?	Job associated with this invoice	See Job Docs
taxCode	TaxCode?	Default tax code to use for items in this invoice	See Tax Code Docs
attachments	File[]	The files associated with the invoice	See File[]
order	Order?	Order associated with this invoice	See Order Docs
paidBy	User?`	User who paid the invoice	See User docs
rejectedBy	User?	User who rejected the invoice	See User docs
vendor	Vendor?	The vendor associated with this invoice	See Vendor docs
costCategory	CostCategory?	Cost category associated with this invoice	See Cost Category docs
glCode	GLCode?	GL code associated with this invoice	See GL Code docs

Enums

InvoiceCategory

Value	Description
genContractor	Invoice is for a general contractor
material	Invoice is for materials
miscellaneous	Invoice falls under miscellaneous expenses
rentals	Invoice is for rentals

InvoiceState

Value	Description
APPROVED	Invoice has been approved
CLOSED	Invoice has been settled and is no longer active
INBOX	Invoice is new
PENDING	Invoice needs to be reviewed and approved
REVIEWED	Invoice has been reviewed
VOIDED	Invoice has been voided

InvoiceIntegrationState

Value	Description
NOT_LINKED	The invoice is not linked to any integrated system, either because no integration is configured or because no attempt has been made to link it
LINKING	Linking to the other system is in progress
LINKED	The invoice was successfully linked to the other system
ERROR	An error occurred while trying to sync the invoice to the other system. When this state is used, it's helpful to set an integrationMessage explaining the problem to the user.

Note: The only Scalar Filter that InvoiceIntegrationState currently supports is integrationState_in.

File

Name	Type	Description	Example
id	ID	Unique identifier for the file	"ckmnpybisiy5x08abky4g2d1f"
name	string?	Name of the file	"document.pdf"
createdAt	DateTime	When this file was created	"2024-09-03T12:00:00Z"
updatedAt	DateTime	When this file was last updated	"2024-09-03T12:00:00Z"
url	string?	URL where the file can be accessed	"https://example.com/file1.pdf"

Queries

invoice

Reads a single invoice by ID.

Parameters

Name	Type	Description	Example
id	ID	ID of the invoice to fetch	"ckmnpybisiy5x08abky4g2d1f"

Response

A single Invoice

Example Query

query {
  invoice(id: "ckmnpybisiy5x08abky4g2d1f") {
    id
    invoiceNumber
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "invoiceNumber": "606123",
}

invoices

Read all invoices, with pagination.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: approvedAt, createdAt, flaggedAt, id, invoiceDate, paidAt, rejectedAt, shipDate, updatedAt, voidedAt.

Allowed filter fields: approvedAt, createdAt, category, flagged, flaggedAt, id, invoiceDate, invoiceNumber, paidAt, rejectedAt, shipDate, state, integrationState_in,taxExempt, type, updatedAt, voidedAt.

Accepts an includeDeleted boolean parameter which determines if deleted invoices will be returned (e.g. includeDeleted: true). By default, deleted invoices are not returned.

Response

A list of Invoice objects.

Example Query

query {
  invoices(orderBy: createdAt, direction: ASC) {
    id
    invoiceNumber
  }
}

Example Response

[
  {
    "id": "ckmnpybisiy5x08aasdf13242",
    "invoiceNumber": "111444",
  },
  {
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "invoiceNumber": "606123",
  }
]

Mutations

markInvoicesAsPaid

Marks invoices as paid.

important

Invoices must be approved before they can be marked as paid. If an invoice is not approved, the entire request will fail.

Parameters

Name	Type	Description	Example
ids	[ID!]	IDs of the invoices to mark as paid	["ckmnpybisiy5x08abky4g2d1f"]
userId	ID!	ID of the user marking the invoices as paid	"ckmnpybisiy5x08abky4g2d1f"

Response

A list of Invoice objects.

Example Query

mutation {
  markInvoicesAsPaid(ids: ["ckmnpybisiy5x08abky4g2d1f"], userId: "ckmnpybisiy5x08abky4g2d1f") {
    id
    state
  }
}

Example Response

[
  {
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "state": "CLOSED",
  }
]

updateInvoiceIntegrationState

Updates the integration state of an invoice.

Parameters

Name	Type	Description	Example
id	ID!	ID of the invoice to update	"ckmnpybisiy5x08abky4g2d1f"
integrationMessage	string?	A message about the status of the integration's sync	"Invoice already exists"
integrationState	InvoiceIntegrationState	The new status of the invoices's sync to your integrated system	NOT_LINKED

Response

A single Invoice object.

Example Query

mutation {
  updateInvoiceIntegrationState(id: "ckmnpybisiy5x08abky4g2d1f", integrationMessage: "Invoice already exists", integrationState: NOT_LINKED) {
    id
    integrationState
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "integrationState": "NOT_LINKED",
}

upsertInvoices

Creates or updates a vendor bill imported from the caller's ERP. Pass Kojo's Invoice.id in the id field to update an existing invoice; omit it to create a new one. Invoices created through this mutation are read-only in the Kojo UI — users can only approve or reject them.

Input types

UpsertInvoicesInput

Name	Type	Description	Example
id	ID?	Kojo Invoice.id from a previous import. When supplied, the invoice is updated; when omitted, a new invoice is created.	"ckmnpybisiy5x08abky4g2d1f"
erpId	String!	ERP-side unique id of the vendor bill. Kept on the payload for logging and audit.	"5142"
orderId	ID!	Kojo Order.id the invoice will be linked to. The caller is responsible for resolving the ERP-side PO id to a Kojo id (e.g. via EntityMetadata for sync-server integrations).	"ckmnpybisiy5x08abky4g2d1f"
vendorId	ID?	Kojo Vendor.id. When omitted, the vendor from the linked PO is used.	"cknmnpybis6y5x08abky4g2d1a"
pdf	UpsertInvoicePdfInput!	Bill PDF. Uploaded to file storage and linked as the invoice's primary file. On update, replaces the current file and appends the previous one as an InvoiceAttachment.	See below
invoiceNumber	String!	ERP-side invoice / bill number. Must be unique per organization.	"VB-2026-08-15"
invoiceDate	DateTime!	Date the bill was issued in the ERP.	"2026-08-15T00:00:00Z"
dueDate	DateTime?	Date the bill is due.	"2026-09-14T00:00:00Z"
memo	String?	Free-text memo carried from the ERP bill.	"Materials for project X"
subtotal	Float?	Pre-tax subtotal.	1000.00
tax	Float?	Sales tax amount.	80.00
totalDue	Float?	Total amount due (subtotal + tax + fees).	1080.00
lines	[UpsertInvoiceLineInput!]!	Bill line items (item and expense lines). At least one line is required.	See below

UpsertInvoicePdfInput

Name	Type	Description	Example
filename	String!	Filename shown in the Kojo UI and preserved on the S3 object.	"vendor-bill-5142.pdf"
contentType	String!	MIME type of the PDF payload.	"application/pdf"
base64	String!	Base64-encoded PDF bytes.	"JVBERi0xLjQKJcOi..."

UpsertInvoiceLineInput

Name	Type	Description	Example
erpId	String?	ERP-side line id. Reserved for future line-level idempotency; not currently used for matching.	"84991"
description	String?	Free-text description of the line item.	"Concrete mix, 80lb bags"
quantity	Float?	Quantity billed.	10
unitPrice	Float?	Unit price billed.	12.50
totalAmount	Float?	Line total (quantity * unitPrice, or the flat amount on expense lines).	125.00
orderItemId	ID?	Kojo OrderItem.id this line should be matched against. When omitted, line matching to the PO is done manually by the approver in the Kojo UI.	"ckmnpybisiy5x08abky4g2d1f"
memo	String?	Free-text memo for the line.	"Delivered on-site"

Response

A single Invoice object.

Example Query

mutation ImportVendorBill($input: UpsertInvoicesInput!) {
  upsertInvoices(input: $input) {
    id
    invoiceNumber
    state
  }
}

Variables:

{
  "input": {
    "erpId": "5142",
    "orderId": "ckmnpybisiy5x08abky4g2d1f",
    "vendorId": "cknmnpybis6y5x08abky4g2d1a",
    "invoiceNumber": "VB-2026-08-15",
    "invoiceDate": "2026-08-15T00:00:00Z",
    "dueDate": "2026-09-14T00:00:00Z",
    "memo": "Materials for project X",
    "subtotal": 1000.00,
    "tax": 80.00,
    "totalDue": 1080.00,
    "pdf": {
      "filename": "vendor-bill-5142.pdf",
      "contentType": "application/pdf",
      "base64": "JVBERi0xLjQKJcOi..."
    },
    "lines": [
      {
        "erpId": "84991",
        "description": "Concrete mix, 80lb bags",
        "quantity": 10,
        "unitPrice": 12.50,
        "totalAmount": 125.00
      }
    ]
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "invoiceNumber": "VB-2026-08-15",
  "state": "PENDING"
}