List patent events by due period

GET /api/v2/external/patent-events

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

Cross-portfolio, paginated list of patent events due within a window. Provide the window via dueFrom+dueTo (YYYY-MM-DD) or the dueMonth (YYYY-MM) shortcut. Optional filters: offices, owners, family, eventTypes (business kind: RENEWAL is the only kind today). include=fees surfaces the estimated fee breakdown on each event. Fuses the legacy /patent-event/{year}/{month} and /estimation endpoints.

Query parameters

Name	Type	Required	Description
`include`	string	No	Comma-separated; `fees` adds the estimated fee breakdown to each event.
`eventTypes`	array of items	No	Business-kind filter (repeatable). RENEWAL is the only kind today: pass it to pin renewals-only ahead of future kinds.
`family`	array of items	No	Family filter.
`owners`	array of items	No	Owner filter.
`offices`	array of items	No	Patent office / authority filter (WO, EP, EA, or national codes).
`dueMonth`	string	No	Shortcut for a whole month (YYYY-MM).
`dueTo`	string	No	Window end, inclusive (YYYY-MM-DD).
`dueFrom`	string	No	Window start, inclusive (YYYY-MM-DD).
`itemsPerPage`	number	No	Number of items per page.
`currentPage`	number	No	Current page.

Response

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

json

{
  "pagination": {
    "totalItems": 128,
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalPages": 13,
    "hasMore": true
  },
  "data": [
    {
      "object": "patentEvent",
      "id": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a",
      "patent": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "providerId": "ACME-2021-0042"
      },
      "eventType": "RENEWAL",
      "dueDate": "2026-10-31",
      "gracePeriodEndDate": "2027-04-30",
      "renewal": {
        "annuityYear": 5
      },
      "appliedDecision": null,
      "duePeriod": "CURRENT",
      "processingStatus": "NOT_INSTRUCTED",
      "processingStatusUpdatedAt": null,
      "isFxRateFrozen": false,
      "feesStatus": "ESTIMATED",
      "createdAt": "2026-01-10T08:30:00.000Z",
      "updatedAt": "2026-07-15T14:00:00.000Z",
      "fees": {
        "object": "fees",
        "invoiceId": null,
        "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a",
        "patent": {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "providerId": "ACME-2021-0042"
        },
        "currency": "EUR",
        "total": "1250.00",
        "components": [
          {
            "type": "OFFICE",
            "amount": "800.00"
          }
        ],
        "feesStatus": "ESTIMATED",
        "isFxRateFrozen": false
      },
      "instructability": {
        "isAllowed": true,
        "allowedDecisions": [
          "PROCEED",
          "SKIP_THIS_TIME",
          "DROP"
        ],
        "blockedReason": null,
        "opensAt": "2026-08-01",
        "mode": "DIRECT"
      }
    }
  ]
}

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: `patentEvent`.
`data[].id`	string	Opaque, stable Renewr UUID of the patent event. Format: `uuid`.
`data[].patent`	object	The patent this event belongs to: identified both ways (Renewr id + your own reference).
`data[].patent.id`	string	Renewr UUID of the patent. Format: `uuid`.
`data[].patent.providerId`	string or null	The client's own matching reference for that patent.
`data[].eventType`	string	Business kind of the event: RENEWAL today; new kinds will be added over time (ignore events whose kind you do not handle). One of: `RENEWAL`.
`data[].dueDate`	string	Due date of the event (renewal / annuity payment deadline).
`data[].gracePeriodEndDate`	string or null	ISO date string.
`data[].renewal`	object or null	Renewal-specific identification: non-null exactly when eventType is RENEWAL (today: every event).
`data[].renewal.annuityYear`	integer	Annuity year covered by the event.
`data[].renewal.paymentSequenceNumber`	integer or null	Office payment sequence number: present only when it differs from annuityYear.
`data[].appliedDecision`	string or null	PROCEED \| SKIP_THIS_TIME \| DROP: the instruction applied to this event. One of: `PROCEED`, `SKIP_THIS_TIME`, `DROP`.
`data[].duePeriod`	string or null	Period of the due date relative to now. One of: `LATE`, `GRACE_PERIOD`, `CURRENT`, `UPCOMING`, `LAPSED`.
`data[].processingStatus`	string or null	Processing status of the event. One of: `NOT_INSTRUCTED`, `INSTRUCTED`, `PAYMENT_SENT`, `PAYMENT_CONFIRMED`, `FULFILLED`, `UNPROCESSABLE`.
`data[].processingStatusUpdatedAt`	string or null	ISO 8601 timestamp (UTC). Format: `date-time`.
`data[].isFxRateFrozen`	boolean	True when the FX rate used to compute fees is frozen.
`data[].feesStatus`	string or null	ESTIMATED (projected) or INVOICED (an invoice exists). One of: `ESTIMATED`, `INVOICED`.
`data[].createdAt`	string or null	ISO 8601 timestamp (UTC). Format: `date-time`.
`data[].updatedAt`	string or null	ISO 8601 timestamp (UTC). Format: `date-time`.
`data[].fees`	object	Estimated fee breakdown for this event: present only when requested via include=fees.
`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 (Stripe fee_details style); 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	Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists). One of: `ESTIMATED`, `INVOICED`.
`data[].fees.isFxRateFrozen`	boolean	True when the FX rate used to compute these fees is frozen.
`data[].instructability`	object	Instruction affordance: whether/how this event can be instructed right now.
`data[].instructability.isAllowed`	boolean	Whether an instruction can be POSTed on this event right now.
`data[].instructability.allowedDecisions`	array of string	Valid decisions right now (empty when not allowed; a lapsed event drops PROCEED).
`data[].instructability.blockedReason`	string or null	Why an instruction is not allowed: ALREADY_INSTRUCTED \| TOO_EARLY \| EARLIER_EVENT_PENDING (null when allowed). One of: `ALREADY_INSTRUCTED`, `TOO_EARLY`, `EARLIER_EVENT_PENDING`.
`data[].instructability.opensAt`	string or null	ISO date string.
`data[].instructability.mode`	string	How an instruction would be processed now: DIRECT executes immediately. One of: `DIRECT`.

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

bash

curl "https://api.renewr.example/api/v2/external/patent-events?dueMonth=2026-10&include=fees" \
  -H "x-api-key: $RENEWR_API_KEY"

List patent events by due period ​

Query parameters ​

Response ​

Errors ​

Example request ​

List patent events by due period

Query parameters

Response

Errors

Example request