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"
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"
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"
flagMessage	string?	User's description of the flagged issue with this invoice	"This invoice is important"
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	20.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 by accident"
salesperson	string?	Salesperson associated with this invoice	"Mikey P."
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	20.55
shipVia	string?	Method of shipment	"Boat"
state	InvoiceState	The current state of the invoice	PENDING
integrationState	IntegrationState	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"
attachments	File[]	The files associated with the invoice	See File[]
subtotal	float?	Subtotal of the invoice before addition of other costs such as taxes	20.55
tax	float?	The amount of tax on the invoice	20.55
terms	string?	Terms of payment for the invoice	"CBS"
totalDue	float?	The total amount due	20.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"

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

IntegrationState

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 IntegrationState 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"

REST Endpoints

GET /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 Request

GET https://api.kojo.tech/invoices?limit=10

Example Response

[
    {
        "id": "ckmnpybisiy5x08abky4g2d1f",
        "title": null,
        "createdAt": "2021-03-24 17:26:46.983Z",
        "updatedAt": "2021-03-24 17:26:46.983Z",
        "approvedAt": null,
        "approvedById": null,
        "category": "miscellaneous",
        "createdById": "clj3k7gl90003ajlj45ld2xdx",
        "dueDate": null,
        "invoiceDate": "2020-06-26T00:00:00.000Z",
        "exceptions": ["totalDue"],
        "flaggedAt": null,
        "flaggedById": null,
        "flagMessage": null,
        "invoiceNumber": "S060988116",
        "paidAt": null,
        "paidById": null,
        "payments": null,
        "rejectedAt": null,
        "rejectedById": null,
        "rejectedReason": null,
        "salesperson": null,
        "shipDate": null,
        "shippingCostFloat": null,
        "shipVia": null,
        "state": "PENDING",
        "subtotal": 1328.22,
        "tax": 79.69,
        "terms": null,
        "totalDue": 1407.91,
        "voidedAt": null,
        "voidedById": null
    }
]

GET /invoices/:id

Reads a single invoice by ID

Parameters

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

Response

A single Invoice.

Example Request

GET https://api.kojo.tech/invoices/ckmnpybisiy5x08abky4g2d1f

Example Response

{
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "title": null,
    "createdAt": "2021-03-24 17:26:46.983Z",
    "updatedAt": "2021-03-24 17:26:46.983Z",
    "approvedAt": null,
    "approvedById": null,
    "category": "miscellaneous",
    "createdById": "clj3k7gl90003ajlj45ld2xdx",
    "dueDate": null,
    "invoiceDate": "2020-06-26T00:00:00.000Z",
    "exceptions": ["totalDue"],
    "flaggedAt": null,
    "flaggedById": null,
    "flagMessage": null,
    "invoiceNumber": "S060988116",
    "paidAt": null,
    "paidById": null,
    "payments": null,
    "rejectedAt": null,
    "rejectedById": null,
    "rejectedReason": null,
    "salesperson": null,
    "shipDate": null,
    "shippingCostFloat": null,
    "shipVia": null,
    "state": "PENDING",
    "subtotal": 1328.22,
    "tax": 79.69,
    "terms": null,
    "totalDue": 1407.91,
    "voidedAt": null,
    "voidedById": null
    }

POST /invoices/paid

Marks invoices as paid.

Parameters

Name	Description	Example
ids	An array of invoice IDs to mark as paid	["ckmnpybisiy5x08abky4g2d1f"]
userId	The ID of the user marking the invoices as paid	"clj3k7gl90003ajlj45ld2xdx"

Response

A list of Invoice objects.

Example Request

POST https://api.kojo.tech/invoices/paid
Content-Type: application/json

{
    "ids": ["ckmnpybisiy5x08abky4g2d1f"],
    "userId": "clj3k7gl90003ajlj45ld2xdx"
}

Example Response

[
    {
        "id": "ckmnpybisiy5x08abky4g2d1f",
        "title": null,
        "createdAt": "2021-03-24 17:26:46.983Z",
        "updatedAt": "2021-03-24 17:26:46.983Z",
        "approvedAt": "2021-03-24 17:26:46.983Z",
        "approvedById": "clj3k7gl90003ajlj45ld2xdx",
        "category": "miscellaneous",
        "createdById": "clj3k7gl90003ajlj45ld2xdx",
        "dueDate": null,
        "invoiceDate": "2020-06-26T00:00:00.000Z",
        "exceptions": ["totalDue"],
        "flaggedAt": null,
        "flaggedById": null,
        "flagMessage": null,
        "invoiceNumber": "S060988116",
        "paidAt": "2021-03-24 17:26:46.983Z",
        "paidById": "clj3k7gl90003ajlj45ld2xdx",
        "payments": null,
        "rejectedAt": null,
        "rejectedById": null,
        "rejectedReason": null,
        "salesperson": null,
        "shipDate": null,
        "shippingCostFloat": null,
        "shipVia": null,
        "state": "CLOSED",
        "subtotal": 1328.22,
        "tax": 79.69,
        "terms": null,
        "totalDue": 1407.91,
        "voidedAt": null,
        "voidedById": null
    }
]