List invoices

GET /api/v2/external/invoices

Authentication: x-api-key header, with the invoices:read scope. See Authentication and limits.

Paginated, unified list of the invoices owned by the authenticated client. Each invoice carries an origin (GENERATED | IMPORTED | REGULARIZATION). This endpoint returns patent invoices (ipRightType=PATENT). Use itemsPerPage and currentPage for pagination (server cap: 100 / page). Filter by issue date with issueDateFrom / issueDateTo (calendar days, both inclusive), or by the day the invoice was recorded with createdFrom / createdTo (both inclusive), all YYYY-MM-DD. For an incremental daily sync, window on createdAt: the issueDate of an IMPORTED invoice is entered by hand and may be backdated, so a window on it would miss such invoices. Sort with ?sort=field (ascending) or ?sort=-field (descending) over issueDate and createdAt (unknown fields are rejected with 400); without sort, invoices come latest issued first.

Query parameters

Name	Type	Required	Description
itemsPerPage	number	No	Number of items per page. Default 10; values above 100 are silently clamped to 100 (hard server cap, spec §6.1).
currentPage	number	No	Current page (1-based). Offset pagination: a page can shift if the collection mutates between calls; re-fetch from page 1 for a consistent sweep.
issueDateFrom	string	No	Issue date window start, inclusive (YYYY-MM-DD): invoices issued on that day or later.
issueDateTo	string	No	Issue date window end, inclusive (YYYY-MM-DD): invoices issued on that day or earlier. Must be on or after issueDateFrom.
createdFrom	string	No	Creation day window start, inclusive (YYYY-MM-DD): invoices recorded on that day or later.
createdTo	string	No	Creation day window end, inclusive (YYYY-MM-DD): invoices recorded on that day or earlier. Must be on or after createdFrom.
sort	string	No	Sort field expressed as field (ASC) or -field (DESC). Allowed fields: issueDate, createdAt. Default: -issueDate.

Response

200 A page of invoices with the standard v2 list envelope { pagination, data }.

{
  "pagination": {
    "totalItems": 128,
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalPages": 13,
    "hasMore": true
  },
  "data": [
    {
      "object": "invoice",
      "id": "c4a1b2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
      "reference": "INV-2026-0087",
      "number": 87,
      "issueDate": "2026-07-22",
      "origin": "GENERATED",
      "ipRightType": "PATENT",
      "currency": "EUR",
      "vatRate": 0.2,
      "vatNumber": "FR12345678901",
      "subtotalExcludingTax": "975.00",
      "totalIncludingTax": "1170.00",
      "hasPdfDocument": true,
      "hasXlsxDocument": false,
      "fees": [
        {
          "object": "fees",
          "invoiceId": "c4a1b2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
          "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a",
          "patent": {
            "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "providerId": "ACME-2021-0042"
          },
          "currency": "EUR",
          "total": "975.00",
          "components": [
            {
              "type": "OFFICE",
              "amount": "800.00"
            },
            {
              "type": "AGENT",
              "amount": "150.00"
            },
            {
              "type": "RENEWR",
              "amount": "25.00"
            }
          ],
          "feesStatus": "INVOICED",
          "isFxRateFrozen": false,
          "regularizedInvoiceId": null,
          "regularizationReason": null
        }
      ],
      "createdAt": "2026-01-10T08:30:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
pagination	object	Pagination metadata.
pagination.totalItems	integer	Total number of items across all pages.
pagination.currentPage	integer	1-based index of the current page.
pagination.itemsPerPage	integer	Number of items per page (server cap: 100).
pagination.totalPages	integer	Total number of pages.
pagination.hasMore	boolean	True when another page exists after the current one.
data	array of objects	Page of results.
data[].object	string	String describing the object type (auto-description). One of: invoice.
data[].id	string	Opaque, stable Renewr UUID of the invoice. Format: uuid.
data[].reference	string	Stable, unique display reference (the only field guaranteed across all 3 origins).
data[].number	string or null	Sequential invoice number; absent (null) for IMPORTED invoices.
data[].issueDate	string or null	ISO date string.
data[].origin	string	One of: GENERATED, IMPORTED, REGULARIZATION.
data[].ipRightType	string	PATENT | TRADEMARK: asset family discriminant. One of: PATENT, TRADEMARK.
data[].currency	string	ISO 4217 currency code the client is invoiced in.
data[].vatRate	number or null	VAT rate applied (non-monetary number, e.g. 0.2 for 20%).
data[].vatNumber	string or null	VAT number on the invoice.
data[].subtotalExcludingTax	string or null	Subtotal before tax, in invoice currency (decimal string).
data[].totalIncludingTax	string or null	Total including tax, in invoice currency (decimal string).
data[].hasPdfDocument	boolean	True when a PDF document is available for this invoice.
data[].hasXlsxDocument	boolean	True when an XLSX document is available for this invoice.
data[].fees	array of objects	Full per-component fee breakdown of the invoice.
data[].fees[].object	string	String describing the object type (auto-description). One of: fees.
data[].fees[].invoiceId	string or null	Back-reference to the invoice these fees belong to. Format: uuid.
data[].fees[].eventId	string or null	Public UUID of the patent event these fees belong to (trace each fee line back to its event). Format: uuid.
data[].fees[].patent	object	The patent this fee line belongs to: identified both ways (Renewr id + your own reference).
data[].fees[].patent.id	string or null	Renewr UUID of the patent. Format: uuid.
data[].fees[].patent.providerId	string or null	The client's own matching reference for that patent.
data[].fees[].currency	string	ISO 4217 currency code the client is invoiced in.
data[].fees[].total	string or null	Total of all components, in invoice currency (decimal string).
data[].fees[].components	array of objects	Per-type fee breakdown; a component that does not apply is absent (never null). Sums to total.
data[].fees[].components[].type	string	OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge). One of: OFFICE, AGENT, RENEWR, GRACE_PERIOD.
data[].fees[].components[].amount	string	Amount of this component, in invoice currency (decimal string).
data[].fees[].feesStatus	string	ESTIMATED (projected, recomputed live) | LOCKED (fixed when the PROCEED instruction was executed, no invoice yet) | INVOICED (an invoice exists, invoiceId set). One of: ESTIMATED, LOCKED, INVOICED.
data[].fees[].isFxRateFrozen	boolean	True when the FX rate used to compute these fees is frozen.
data[].fees[].regularizedInvoiceId	string or null	Lines of a REGULARIZATION invoice only: UUID of the original invoice whose line is regularized. Null on every other line. Format: uuid.
data[].fees[].regularizationReason	string or null	Lines of a REGULARIZATION invoice only: NOT_PAYABLE (the original fees are credited) | ANNUITY_ERROR (office and grace fees corrected) | ACCOUNTING_ERROR (invoiced amounts corrected). Null on every other line. One of: NOT_PAYABLE, ANNUITY_ERROR, ACCOUNTING_ERROR.
data[].createdAt	string	Timestamp at which the invoice was recorded in Renewr. The reliable bound for an incremental sync: the issueDate of an IMPORTED invoice is entered by hand and may be backdated. Format: date-time.

Errors

Errors use the application/problem+json envelope with stable machine-readable codes. See the Errors guide.

Status	Description
400	Validation failed (validation_failed): carries per-field errors[] with RFC 6901 JSON Pointers.
401	Missing or invalid API key (invalid_api_key), or expired key (api_key_expired).
403	API key lacks the required scope (insufficient_scope, with requiredScope extension) or the operation is not enabled for this client (forbidden).
429	Daily API call limit exceeded (rate_limit_exceeded): the Retry-After header gives the seconds until reset.

Example request

curl "https://api.renewr.example/api/v2/external/invoices?createdFrom=2026-09-11&createdTo=2026-09-11&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"