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.

Returns the events (renewals / annuities) of a single patent, identified by its Renewr UUID.

Path parameters

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

Response

200 The events of the patent.

[
  {
    "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
[].object	string	String describing the object type (auto-description). One of: patentEvent.
[].id	string	Opaque, stable Renewr UUID of the patent event. Format: uuid.
[].patent	object	The patent this event belongs to: identified both ways (Renewr id + your own reference).
[].patent.id	string	Renewr UUID of the patent. Format: uuid.
[].patent.providerId	string or null	The client's own matching reference for that patent.
[].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.
[].dueDate	string	Due date of the event (renewal / annuity payment deadline).
[].gracePeriodEndDate	string or null	ISO date string.
[].renewal	object or null	Renewal-specific identification: non-null exactly when eventType is RENEWAL (today: every event).
[].renewal.annuityYear	integer	Annuity year covered by the event.
[].renewal.paymentSequenceNumber	integer or null	Office payment sequence number: present only when it differs from annuityYear.
[].appliedDecision	string or null	PROCEED | SKIP_THIS_TIME | DROP: the instruction applied to this event. One of: PROCEED, SKIP_THIS_TIME, DROP.
[].duePeriod	string or null	Period of the due date relative to now. One of: LATE, GRACE_PERIOD, CURRENT, UPCOMING, LAPSED.
[].processingStatus	string or null	Processing status of the event. One of: NOT_INSTRUCTED, INSTRUCTED, PAYMENT_SENT, PAYMENT_CONFIRMED, FULFILLED, UNPROCESSABLE.
[].processingStatusUpdatedAt	string or null	ISO 8601 timestamp (UTC). Format: date-time.
[].isFxRateFrozen	boolean	True when the FX rate used to compute fees is frozen.
[].feesStatus	string or null	ESTIMATED (projected) or INVOICED (an invoice exists). One of: ESTIMATED, INVOICED.
[].createdAt	string or null	ISO 8601 timestamp (UTC). Format: date-time.
[].updatedAt	string or null	ISO 8601 timestamp (UTC). Format: date-time.
[].fees	object	Estimated fee breakdown for this event: present only when requested via include=fees.
[].fees.object	string	String describing the object type (auto-description). One of: fees.
[].fees.invoiceId	string or null	Back-reference to the invoice these fees belong to. Format: uuid.
[].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.
[].fees.patent	object	The patent this fee line belongs to: identified both ways (Renewr id + your own reference).
[].fees.patent.id	string or null	Renewr UUID of the patent. Format: uuid.
[].fees.patent.providerId	string or null	The client's own matching reference for that patent.
[].fees.currency	string	ISO 4217 currency code the client is invoiced in.
[].fees.total	string or null	Total of all components, in invoice currency (decimal string).
[].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.
[].fees.components[].type	string	OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge). One of: OFFICE, AGENT, RENEWR, GRACE_PERIOD.
[].fees.components[].amount	string	Amount of this component, in invoice currency (decimal string).
[].fees.feesStatus	string	Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists). One of: ESTIMATED, INVOICED.
[].fees.isFxRateFrozen	boolean	True when the FX rate used to compute these fees is frozen.
[].instructability	object	Instruction affordance: whether/how this event can be instructed right now.
[].instructability.isAllowed	boolean	Whether an instruction can be POSTed on this event right now.
[].instructability.allowedDecisions	array of string	Valid decisions right now (empty when not allowed; a lapsed event drops PROCEED).
[].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.
[].instructability.opensAt	string or null	ISO date string.
[].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"