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

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"

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