Skip Navigation
Log In Sign Up

List All Invoices

·

Retrieve a paginated list of all invoices with optional filtering.

Request

GET https://tupel.com/api/invoices/

Authentication

This endpoint requires basic authentication with your Organization ID and API Key.

Query Parameters

  • created_from timestamp Optional
    Filter invoices created on or after this timestamp. Format: ISO 8601 (e.g., 2023-01-01T00:00:00Z).

  • created_to timestamp Optional
    Filter invoices created on or before this timestamp. Format: ISO 8601 (e.g., 2023-12-31T23:59:59Z).

  • updated_from timestamp Optional
    Filter invoices updated on or after this timestamp. Format: ISO 8601 (e.g., 2023-01-01T00:00:00Z).

  • updated_to timestamp Optional
    Filter invoices updated on or before this timestamp. Format: ISO 8601 (e.g., 2023-12-31T23:59:59Z).

  • entity string Optional
    Filter invoices by entity UID. Only returns invoices associated with the specified entity.

  • status string Optional
    Filter invoices by status. Possible values: ISSUED, PAID, OVERDUE.

  • currency string Optional
    Filter invoices by currency. Possible values: USD, EUR, GBP, or other accepted currency codes.

  • order_by string Optional
    Field to sort the results by. Prefix with - for descending order (e.g., -created_at).

  • page integer Optional
    Page number for pagination. Default: 1.

  • page_size integer Optional
    Number of items per page. Default: 10. Maximum: 100.

Notes

  • By default, all invoices are returned, sorted by creation date (newest first).
  • Use the filtering parameters to narrow down results for better performance with large datasets.
  • For date range filters, both the start and end parameters are inclusive.
  • This endpoint uses page-based pagination with 10 items per page by default.
  • For more information about working with paginated results, see the pagination documentation.
  • Common use cases include:
  • Retrieving all overdue invoices for follow-up
  • Monitoring recently issued invoices
  • Generating reports filtered by date ranges and status
  • Tracking invoices for a specific entity

Example Request

curl -X GET "https://tupel.com/api/invoices/?status=OVERDUE" \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY>

Response

A successful request returns a 200 OK status code and a paginated list of Invoices in the response body.

Response Format

The response follows Tupel's standard pagination format with these fields:

  • count integer
    Total number of invoices matching the filter criteria.

  • next string or null
    URL to fetch the next page of results, or null if this is the last page.

  • previous string or null
    URL to fetch the previous page of results, or null if this is the first page.

  • items array
    Array of Invoice objects, limited to the specified page size.

Error Responses

Code Description
401 Unauthorized - Authentication failed. Check your Organization ID and API Key.
403 Forbidden - Insufficient permissions to list invoices.
422 Unprocessable Entity - Invalid filter parameters provided.

Example Error Response

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query", "status"],
      "msg": "Invalid status value. Must be one of: ISSUED, PAID, OVERDUE."
    }
  ]
}