List the events of a patent

GET /api/v2/external/patents/{patentId}/events

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

Paginated list of the events (renewals / annuities) of a single patent, identified by its Renewr UUID. Standard v2 list envelope { pagination, data }; events are ordered by due date.

Path parameters

Name	Type	Required	Description
patentId	string	Yes	The opaque, stable Renewr UUID of the patent.

Response

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

{
  "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": "975.00",
        "components": [
          {
            "type": "OFFICE",
            "amount": "800.00"
          },
          {
            "type": "AGENT",
            "amount": "150.00"
          },
          {
            "type": "RENEWR",
            "amount": "25.00"
          }
        ],
        "feesStatus": "ESTIMATED",
        "isFxRateFrozen": false,
        "regularizedInvoiceId": null,
        "regularizationReason": null
      },
      "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) | LOCKED (amounts fixed at PROCEED execution, not yet invoiced) | INVOICED (an invoice exists). One of: ESTIMATED, LOCKED, 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	Fee breakdown for this event (ESTIMATED, LOCKED or INVOICED): 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; 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[].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 (null when allowed). Maps 1:1 onto the POST error codes: ALREADY_INSTRUCTED → instruction_already_set (409), TOO_EARLY → instruction_too_early (422), EARLIER_EVENT_PENDING → instruction_skipped (422). 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).
404	The resource does not exist in your portfolio (not_found).
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/patents/$PATENT_ID/events" \
  -H "x-api-key: $RENEWR_API_KEY"