Skip to main content
GET
/
external
/
invoices
Handles GET requests for the /invoices route
curl --request GET \
  --url https://api.valyx.com/external/invoices \
  --header 'X-Valyx-Signature: <x-valyx-signature>'
{
  "error": "<string>",
  "message": "<string>",
  "data": {
    "totalDocs": 123,
    "docs": [
      {
        "id": "<string>",
        "invoiceId": "<string>",
        "invoiceNumber": "<string>",
        "invoiceDate": "2023-12-25",
        "invoiceDueDate": "2023-12-25",
        "promiseToPayDate": "2023-12-25",
        "invoiceSubtotal": 123,
        "invoiceTotal": 123,
        "invoicePaidAmount": 123,
        "invoiceAdjustedAmount": 123,
        "invoiceOutstandingAmount": 123,
        "writtenOffAmount": 123,
        "roundOffAmount": 123,
        "creditNoteAdjustedAmount": 123,
        "invoiceTax": {},
        "discount": {},
        "buyerId": "<string>",
        "customerName": "<string>",
        "lineItems": [
          {}
        ],
        "referenceType": "<string>",
        "referenceId": "<string>",
        "referenceText": "<string>",
        "createdAt": "2026-03-23 14:05:11",
        "updatedAt": "2026-03-24 09:17:02",
        "createdBy": {
          "userId": "<string>",
          "userName": "<string>"
        },
        "invoiceAmountAdjustments": [
          {}
        ],
        "irnNumber": "<string>",
        "placeOfSupply": "<string>",
        "invoiceCurrency": "<string>",
        "erpId": "<string>",
        "invoiceTds": {},
        "invoiceBillingAddress": {},
        "invoiceShippingAddress": {},
        "invoiceGeneralTerms": "<string>",
        "invoicePaymentTerms": "<string>",
        "invoiceSellerDetails": {},
        "billingPeriod": {
          "startDate": "2023-12-25",
          "endDate": "2023-12-25"
        },
        "einvoiceAcknowledgementNumber": 123,
        "einvoiceAcknowledgedAt": "<string>",
        "buyerGstin": "<string>"
      }
    ],
    "hasNext": true,
    "hasPrev": true,
    "pageNumber": 123,
    "pageSize": 123,
    "totalPages": 123,
    "prevPageNumber": 123,
    "nextPageNumber": 123
  }
}

Headers

​
X-Valyx-Signature
string
required

Auth key for fetching ledger entries

Query Parameters

​
invoiceStatus
string[]

list of invoice statuses to filter by

​
paymentStatus
string[]

list of payment statuses to filter by

​
invoiceAcceptanceStatus
string[]

list of invoice acceptance statuses to filter by

​
tag
string[]

list of tag key-value pair to filter by

​
customerIds
string

List of customer IDs

​
ownerIds
string

List of owner IDs

​
buyerIds
string[]

List of buyer IDs

​
sort
enum<string>

Invoices support sorting by invoice date. Passing 'invoiceDate' sorts ascending. To reverse the order, prefix with a hyphen.

Available options:
invoiceDate,
-invoiceDate
​
amountType
enum<string>

Amount type filter

Available options:
TOTAL,
OUTSTANDING,
PAID,
ADJUSTED
​
amountMin
number

Minimum amount of the invoice amount type

​
amountMax
number

Maximum amount of the invoice amount type

​
dateType
enum<string>

Field that startDate / endDate apply to. CREATED_AT filters by when the invoice was created in Valyx, UPDATED_AT by when it was last modified. For CREATED_AT / UPDATED_AT the end-date comparison is performed on DATE(column), so the full end day is included; the other date types compare against the date column directly.

Available options:
INVOICE_DATE,
DUE_DATE,
PROMISE_TO_PAY_DATE,
CREATED_AT,
UPDATED_AT
​
startDate
string

Start date for the selected dateType. Pass as YYYY-MM-DD.

​
endDate
string

End date for the selected dateType. Pass as YYYY-MM-DD.

​
originSource
enum<string>[]

Filter invoices by where they originated. Repeat the param to pass multiple values (e.g. ?originSource=VALYX&originSource=ZOHO). Matches the invoiceOriginSource value stored on the invoice-extra row.

Available options:
ZOHO,
IRECKONER,
BOLTIC,
VALYX,
OTHER
​
lifecycleStatuses
enum<string>[]

Filter invoices by lifecycle status. Repeat the param to pass multiple values (e.g. ?lifecycleStatuses=FINALIZED&lifecycleStatuses=DRAFT).

Default behavior change: by default the response now includes DRAFT, FINALIZED, and VOIDED invoices (previously DRAFT and VOIDED were excluded). Callers that need only finalized invoices must pass lifecycleStatuses=FINALIZED explicitly.

DELETED is accepted by the parser but yields no results — deleted invoices are always excluded from this endpoint.

Available options:
DRAFT,
FINALIZED,
VOIDED,
DELETED
​
page
integer
required

page number of result to be fetched

​
pageSize
integer
required

number of entries per page

​
onlyFetchNonZero
boolean

should return invoices that have non zero amount type

​
invoiceNumber
string

invoice number

​
internalInvoiceIds
string[]

invoice ids

​
hasAttachment
string

should return invoices that have attachments (true/false)

​
attachmentPurpose
string[]

attachment purpose to search by (based on hasAttachment)

​
currencies
string[]

Currencies

Response

200 - application/json

Success

​
error
string | null
​
message
string
​
data
object