Get Invoices

get/v1/invoices

Returns a paginated list of invoices for the active workspace with optional filtering, sorting, and relationship includes. Read only, no side effects. For example, an Anthropic invoice billed to Foldspace AI. ## Filtering & sorting Filter via `POST /v1/records/query` (root `invoices`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `accounting_currency` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `accounting_grand_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `accounting_items_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `accounting_tax_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `balance_due` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `billing_context` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `composite_fx_rate` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoice_items_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoice_payment_means_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoice_preview` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoice_transactions_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_items_amount_currency` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_journal_entries_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_ledger_accounts_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_routed_to` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_sourced_from` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_tax_amount_currency` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_total_amount_currency` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_transactions_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `description` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `document_type_code` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `due_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `grand_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `invoice_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `invoice_number` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `issue_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `items_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `last_payment_allocation_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `local_currency` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `override_version` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `paid_amount` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `payment_status` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `purchase_order_number` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `reference_number` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `shadow_from_receipt` | boolean | `eq` | | `status` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `tax_total` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `terms` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `accounting_currency`, `accounting_grand_total`, `accounting_items_total`, `accounting_tax_total`, `balance_due`, `billing_context`, `composite_fx_rate`, `composite_invoice_items_list`, `composite_invoice_payment_means_list`, `composite_invoice_preview`, `composite_invoice_transactions_list`, `composite_items_amount_currency`, `composite_journal_entries_list`, `composite_ledger_accounts_list`, `composite_routed_to`, `composite_sourced_from`, `composite_tax_amount_currency`, `composite_total_amount_currency`, `composite_transactions_list`, `created_at`, `deleted_at`, `description`, `document_type_code`, `due_date`, `grand_total`, `invoice_id`, `invoice_number`, `issue_date`, `items_total`, `last_payment_allocation_date`, `local_currency`, `override_version`, `paid_amount`, `payment_status`, `pk`, `purchase_order_number`, `reference_number`, `status`, `tax_total`, `terms`, `updated_at` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

NameTypeRequiredDescription
pagestringNo1-based page number for offset pagination. Defaults to 1.e.g. 1
limitstringNoRecords per page, 1 to 100. Defaults to 25.e.g. 25
sortstringNoComma-separated sort fields; prefix a field with - for descending (e.g. -issue_date,grand_total).e.g. -issue_date
includestringNoComma-separated related resources to sideload: issuer, receiver, invoice_items, payment_means, document, images, workspace.e.g. issuer,invoice_items
filter[status]stringNoFilter by invoice status.e.g. issued
filter[currency]stringNoFilter by ISO 4217 currency code.e.g. USD
filter[issuer_id]string <uuid>NoFilter by issuer company UUID.e.g. 22222222-0000-4000-8000-0000000000c1
filter[reference_number]stringNoExact match on the invoice reference number.e.g. ANT-2026-0412

Request

cURL
curl -X GET https://api.wellapp.ai/v1/invoices \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — A page of invoices.

{
  "data": [
    {
      "type": "invoice",
      "id": "11111111-0000-4000-8000-0000000000b1",
      "attributes": {
        "reference_number": "ANT-2026-0412",
        "issue_date": "2026-04-12",
        "due_date": "2026-05-12",
        "currency": "USD",
        "document_type_code": "380",
        "terms": "Net 30",
        "status": "issued",
        "billing_context": "subscription",
        "description": "Claude API usage, April 2026",
        "totals": {
          "items_total": 1200,
          "tax_total": 0,
          "grand_total": 1200
        },
        "payment_status_value": "unpaid",
        "override_version": 0,
        "created_at": "2026-04-12T08:00:00Z",
        "updated_at": "2026-04-12T08:00:00Z",
        "deleted_at": null
      },
      "relationships": {
        "issuer": {
          "data": {
            "type": "company",
            "id": "22222222-0000-4000-8000-0000000000c1"
          }
        },
        "receiver": {
          "data": {
            "type": "company",
            "id": "22222222-0000-4000-8000-0000000000c2"
          }
        },
        "invoice_items": {
          "data": [
            {
              "type": "invoice_item",
              "id": "33333333-0000-4000-8000-0000000000d1"
            }
          ]
        },
        "payment_means": {
          "data": []
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 1,
      "total_pages": 1
    }
  }
}

400 — Bad request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

Complex Usage Example

Advanced Invoice Filtering with Full Context

This example demonstrates advanced filtering with multiple parameters, status filtering, company relationships, and pagination for retrieving invoices:

curl -X GET "https://api.well.com/v1/invoices?issuer_id=550e8400-e29b-41d4-a716-446655440001&receiver_id=550e8400-e29b-41d4-a716-446655440002&status=sent&date_from=2025-01-01&date_to=2025-12-31&page[limit]=20&page[cursor]=eyJkYXRlIjoiMjAyNS0xMS0wMiIsImlkIjoiaW52b2ljZTktdXVpZCJ9" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Filtering & sorting on related objects

Filter and sort on a related (included) object by nesting into the relationship — the same relationships you pass to include.

  • To-one relations nest directly: { "issuer": { "name": { "_eq": "Acme" } } }, and sort by a dot-path: "orderBy": { "field": "issuer.name", "direction": "asc" }.
  • To-many relations must be quantified with _some, _every, or _none: { "items": { "_some": { "quantity": { "_gt": 1 } } } }. They are not directly sortable (a to-many sort needs an aggregate proxy).
  • Composite composite_* columns are virtual — filter and sort on their underlying source fields, not on the composite.

Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: Filtering & sorting.

This resource's related objects (the ones you can include) and how to filter or sort on each:

RelationshipCardinalityFilter on a fieldSort by a field
issuerto-one (company){ "issuer": { "name": { "_eq": … } } }"field": "issuer.name" ✅
receiverto-one (company){ "receiver": { "name": { "_eq": … } } }"field": "receiver.name" ✅
documentto-one (document){ "document": { "file_name": { "_eq": … } } }"field": "document.file_name" ✅
workspaceto-one (workspace){ "workspace": { "name": { "_eq": … } } }"field": "workspace.name" ✅
source_workspace_connectorto-one (workspace_connector){ "source_workspace_connector": { "name": { "_eq": … } } }"field": "source_workspace_connector.name" ✅
exchange_rateto-one (exchange_rate){ "exchange_rate": { "rate_date": { "_eq": … } } }"field": "exchange_rate.rate_date" ✅
subscriptionto-one (subscription){ "subscription": { "status": { "_eq": … } } }"field": "subscription.status" ✅
invoice_itemsto-many (invoice_item){ "invoice_items": { "_some": { "amount": { "_eq": … } } } }aggregate proxy only ⚠️
invoice_transactionsto-many (invoice_transaction){ "invoice_transactions": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️
payment_meansto-many (invoice_payment_means){ "payment_means": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️
invoice_workspace_connectorsto-many (invoice_workspace_connector){ "invoice_workspace_connectors": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️

Replace field_name with any field of the related object. See its object-reference page for the full field list.

Filter by a to-one relation (and sort by it):

{
  "root": "invoices",
  "whereClause": { "issuer": { "name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "issuer.name", "direction": "asc" }
}

Filter by a to-many relation (quantified — bare nesting is invalid):

{
  "root": "invoices",
  "whereClause": { "invoice_items": { "_some": { "amount": { "_gt": 0 } } } }
}