List Invoices

GET /api/v1/invoices

Retrieve a paginated list of all invoices for the authenticated business. Filtering, sorting, and searching are powered by the Ransack gem, allowing flexible query parameters prefixed with q[] for conditions, s[] for sorting, and standard pagination params.

Parameters

Ransack supports a wide range of predicates (e.g., _eq, _not_eq, _gt, _lt, _cont, _starts_with) on searchable attributes. Common attributes include: id, number, status, issued_at, due_at, customer_id, subtotal, total, balance, created_at, updated_at.

Pagination

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1).
`per_page`	integer	No	Records per page (default: 25, max: 100).

Filtering & Searching (Ransack)

Parameter Example	Type	Required	Description
`q[status_eq]`	string	No	Exact match for status (e.g., `draft`, `sent`, `paid`).
`q[customer_id_eq]`	integer	No	Filter by exact customer ID.
`q[issued_at_gteq]`	date (YYYY-MM-DD)	No	Issued on or after this date.
`q[issued_at_lteq]`	date (YYYY-MM-DD)	No	Issued on or before this date.
`q[number_cont]`	string	No	Partial match on invoice number.
`q[total_gt]`	decimal	No	Total greater than value.
`q[status_in]`	array (comma-separated)	No	Multiple statuses (e.g., `sent,paid`).
`q[notes_cont]`	string	No	Search in notes.

Sorting (Ransack)

Parameter	Type	Required	Description
`s`	string	No	Sort by attribute (e.g., `issued_at desc`, `total asc`). Multiple sorts: `s[0]=issued_at desc&s[1]=total asc`.

For full Ransack syntax, refer to the Ransack documentation. Invalid or unsupported predicates return 422 Unprocessable Entity.

Request Example

GET /api/v1/invoices?q[status_eq]=sent&q[issued_at_gteq]=2025-10-01&s=issued_at+desc&page=1&per_page=10 HTTP/1.1
Host: koteshen.com
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

Response

Status Codes:

200 OK - Success.
401 Unauthorized - Invalid or missing token.
422 Unprocessable Entity - Invalid Ransack query parameters.

Success Response (200)

{
  "data": [
    {
      "id": 123,
      "number": "INV-001",
      "status": "sent",
      "issued_at": "2025-10-12T00:00:00.000Z",
      "due_at": "2025-11-11T00:00:00.000Z",
      "currency": "USD",
      "subtotal": "380.00",
      "discount_total": "19.00",
      "tax_total": "38.00",
      "total": "399.00",
      "balance": "399.00",
      "customer_id": 13,
      "customer": {
        "id": 13,
        "name": "Texas Ins",
        "email": "procurement@texas.com",
        "company": "Texas Ins"
      },
      "items": [
        {
          "id": 172,
          "name": "Items Consulting",
          "quantity": 1,
          "unit_price": "400.00",
          "total": "400.00"
        }
      ],
      "notes": "",
      "url": "https://koteshen.com/api/v1/invoices/123",
      "pdf_url": "https://koteshen.com/api/v1/invoices/123/pdf",
      "created_at": "2025-10-12T19:00:37.057Z",
      "updated_at": "2025-10-12T19:09:27.293Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "prev_page": null,
      "next_page": null,
      "total_pages": 1,
      "total_count": 5
    }
  },
  "links": {
    "first": "https://koteshen.com/api/v1/invoices?page=1",
    "last": "https://koteshen.com/api/v1/invoices?page=1",
    "self": "https://koteshen.com/api/v1/invoices?page=1"
  }
}

We are using cookies to improve your experience!