Invoices Queries

Retrieve invoices, their line items, payment status, and accounting details.

`Invoice` — Returns a single invoice by `id`

query GetInvoice($id: ID!) {
  Invoice(id: $id) {
    id
    label
    status
    total
    dated_at
    due_at
    customer { id label }
    paid_amount
    remaining_balance
    line_items {
      id
      variant { id label }
      quantity
      price
    }
  }
}

`Invoices` — Returns a paginated list of invoices with sorting and filters

query Invoices(
  $where: QueryInvoicesWhereWhereConditions,
  $orderBy: [QueryInvoicesOrderByOrderByClause!],
  $search: String,
  $first: Int,
  $page: Int
) {
  Invoices(
    where: $where,
    orderBy: $orderBy,
    search: $search,
    first: $first,
    page: $page
  ) {
    paginatorInfo {
      total
      currentPage
    }
    data {
      id
      label
      status
      dated_at
      total
      customer { id label }
    }
  }
}

Available fields

Field	Type	Description
`id`	Int	Unique identifier.
`label`	String	Invoice number.
`status`	InvoiceStatus	Payment and publication status.
`deposit`	Boolean	True if it's a deposit (down payment) invoice.
`exchange_rate`	Float	Exchange rate used.
`tax_type`	TaxType	Tax calculation method.
`default_discount`	Float	Global discount value.
`discount_type`	DiscountType	Discount type.
`total_units`	Float	Sum of all line item quantities.
`subtotal`	Float	Net amount before taxes and discounts.
`total_without_tax`	Float	Amount excluding taxes.
`total_ecotax`	Float	Sum of environmental taxes.
`total`	Float	Grand total including everything.
`paid_amount`	Float	Total amount received through payments.
`remaining_balance`	Float	Unpaid balance remaining.
`dated_at`	Date	Document date.
`due_at`	Date	Deadline for payment.
`notes`	String	Public notes displayed on the PDF.
`internal_notes`	String	Hidden internal comments.
`for_the_attention_of`	String	Specific recipient name.
`external_reference`	String	Merchant internal reference.
`vat_payment_method`	String	VAT strategy (e.g. "on payments").
`location_label`	String	Name of the warehouse/store.
`public_id`	String	Secure token for external viewing.
`public_view_count`	Int	Number of times viewed via public link.
`public_last_accessed_at`	JSON	Timestamp of last public access.
`currency`	Currency	Invoice currency.
`customer`	Customer	Associated customer.
`price_level`	PriceLevel	Applied price list.
`account_representative`	AccountRepresentative	Assigned sales rep.
`season`	Season	Business season.
`payment_information`	PaymentInformation	Bank details for payment.
`return_status`	ReturnStatus	Goods return progress.
`credit_status`	CreditStatus	Credit note progress.
`returned_quantity`	Float	Quantity returned so far.
`unreturned_quantity`	Float	Quantity still pending return.
`credited_quantity`	Float	Quantity already credited.
`uncredited_quantity`	Float	Quantity still pending credit.
`credited_amount`	Float	Value already processed for credit.
`uncredited_amount`	Float	Value still pending credit.
`pdf_template`	PdfTemplate	Template used for generation.
`billing_address`	Address	Document billing address.
`shipping_address`	Address	Delivery address.
`line_items`	[LineItemInvoice]	Detailed list of items.
`total_taxes`	[DocumentTaxRate]	Summary of taxes.
`estimates_count`	Int	Number of source estimates.
`estimates`	[Estimate]	Linked estimates history.
`orders_count`	Int	Number of source sales orders.
`orders`	[Order]	Linked sales orders history.
`shipping_orders_count`	Int	Number of linked deliveries.
`shipping_orders`	[ShippingOrder]	Linked shipping orders history.
`product_returns_count`	Int	Number of linked returns.
`product_returns`	[ProductReturn]	Linked product returns history.
`credit_notes_count`	Int	Number of linked credit notes.
`credit_notes`	[CreditNote]	Linked credit notes history.
`invoice_payments`	[InvoicePayment]	List of payment allocations.
`integrations`	[Integration]	External platform links.
`email_histories`	[EmailHistory]	Email logs.
`files`	[File]	Attachments.
`has_batch_numbers`	Boolean	True if invoice items use batch tracking.
`custom_fields`	[EntityCustomField]	Custom fields for this entity.

Filters

The following fields can be used in the where parameter:

id, label, status, currency, deposit, exchange_rate, tax_type, default_discount, discount_type, total_units, subtotal, total_without_tax, total_ecotax, total, dated_at, due_at, notes, internal_notes, for_the_attention_of, tracking_completed, created_at, updated_at, customer_id, price_level_id, account_representative_id, season_id, pdf_template_id, payment_information_id, paid_amount, remaining_balance, variant_id, variant_label, variant_sku, location_id, batch_number_id, returned_quantity, unreturned_quantity, credited_quantity, uncredited_quantity, credited_amount, uncredited_amount, estimates_count, orders_count, shipping_orders_count, product_returns_count, credit_note_count, product_tag_id, customer_tag_id, shipping_type, source, credit_note_id, payment_method_id, is_sent, return_status, credit_status.

Example Filters:

Field	Example
`status`	`{ "column": "STATUS", "operator": "EQ", "value": "unpaid" }`
`remaining_balance`	`{ "column": "REMAINING_BALANCE", "operator": "GT", "value": 0 }`
`customer_id`	`{ "column": "CUSTOMER_ID", "operator": "EQ", "value": 100050 }`
`dated_at`	`{ "column": "DATED_AT", "operator": "GTE", "value": "2025-01-01" }`

Sorting

You can sort results using the orderBy parameter:

id
label
status
dated_at
due_at
total
paid_amount
remaining_balance

Grouping Options

You can group invoices using the groupBy parameter for reports:

Field	Description
`id`	Group by internal ID.
`year`	Group by year of `dated_at`.
`month`	Group by month of `dated_at`.
`day`	Group by day of `dated_at`.

Data Types

`EInvoiceValidationResult`

Field	Type	Description
`valid`	Boolean	Whether the e-invoice is valid.
`checks`	[EInvoiceValidationCheck]	List of validation checks.
`errors`	[String]	List of error messages.
`message`	String	Summary message.
`invoice`	Invoice	The validated invoice.

`EInvoiceValidationCheck`

Field	Type	Description
`field`	String	Field that was validated.
`label`	String	Human-readable field label.
`valid`	Boolean	Whether the check passed.
`message`	String	Validation message.

Enums

`InvoiceStatus`

Value	Description
`unpublished`	Draft status (hidden).
`draft`	Document created, not yet published.
`unpaid`	Published and awaiting payment.
`partially_paid`	Partial payment received.
`paid`	Fully paid.
`cancelled`	Document voided.
`sent_to_quickbooks`	Exported to QB.

`ReturnStatus`

Value	Description
`not_returned`	Default state.
`partially_returned`	Partial returns linked.
`returned`	Fully returned.

`CreditStatus`

Value	Description
`not_credited`	Default state.
`partially_credited`	Active credit notes linked.
`credited`	Fully credited.

`EInvoiceStatus`

Value	Description
`accepted`	E-invoice accepted.
`approved`	E-invoice approved.
`collected`	E-invoice collected.
`in_dispute`	E-invoice in dispute.
`partially_collected`	E-invoice partially collected.
`refused`	E-invoice refused.
`rejected`	E-invoice rejected.
`sent`	E-invoice sent.
`submitted`	E-invoice submitted.

`DiscountType`

Value	Description
`amount`	Fixed discount amount.
`percentage`	Percentage-based discount.

`TaxType`

Value	Description
`exclusive`	Tax calculated on top of the net price.
`inclusive`	Tax included in the displayed price.

Invoice — Returns a single invoice by id

Invoices — Returns a paginated list of invoices with sorting and filters

Available fields

Filters

Sorting

Grouping Options

Data Types

EInvoiceValidationResult

EInvoiceValidationCheck

Enums

InvoiceStatus

ReturnStatus

CreditStatus

EInvoiceStatus

DiscountType

TaxType