The renewal lifecycle

Every patent annuity managed by Renewr follows the same six-stage path: the patent enters your portfolio, its renewal deadlines are computed, the expected cost is estimated, you decide what to do, Renewr executes and pays, and finally you are invoiced, with documentary proof at each step. This page walks that pipeline end to end and shows which API call matters at each stage.

If you are integrating for the first time, read this page before the getting started guide: every other concept page hangs off this timeline.

1. Your portfolio in Renewr

Your patents are imported and kept in sync by the Renewr team. Through the API, the patent resource is read-only: you browse your portfolio with GET /patents and fetch a single patent with GET /patents/{patentId}. There is no endpoint to create or modify a patent; portfolio changes go through your Renewr contact.

Each patent carries two identifiers:

Field	Who assigns it	Role
id	Renewr	Opaque, stable UUID. The only identifier used in URL paths.
providerId	You (at import)	Your own reference for the patent, used for matching against your IPMS or docketing system.

Look up a patent by your own reference

GET /patents accepts ?providerId= as an exact-match filter. An unknown value returns an empty page with HTTP 200. It never responds 404 for an unknown providerId. Wherever an event or a fee line references its patent, both keys are grouped as patent: { id, providerId }, so you can always join API data back to your own records without extra lookups.

Your firm's docketing references (clientCaseReference, clientFamilyReference) are also exposed on the patent. See the glossary for the full vocabulary.

2. Renewal events are computed

For every patent, Renewr computes all future renewal deadlines from office-specific rule matrices (each office has its own cadence, grace rules, and base date). Each annuity falling due becomes one event:

• dueDate: the date the fee must be paid by.
• renewal.annuityYear: which year of the patent's life this fee pays for.
• gracePeriodEndDate: the end of the office's grace window, after which the right lapses.

{
  "object": "patentEvent",
  "id": "0e8b1f14-6c2a-4f6e-9b0d-3a5c7d9e1f22",
  "patent": { "id": "7f3a2c10-9d4e-4b8a-8c1d-2e5f6a7b8c90", "providerId": "ACME-EP-0042" },
  "eventType": "RENEWAL",
  "dueDate": "2026-11-30",
  "gracePeriodEndDate": "2027-05-31",
  "renewal": { "annuityYear": 5, "paymentSequenceNumber": null },
  "duePeriod": "UPCOMING",
  "processingStatus": "NOT_INSTRUCTED",
  "instructability": {
    "isAllowed": false,
    "allowedDecisions": [],
    "blockedReason": "TOO_EARLY",
    "opensAt": "2026-09-01",
    "mode": "DIRECT"
  }
}

(abridged; see the event reference for the full shape)

You read events two ways:

• Per patent: GET /patents/{patentId}/events (the response is a bare JSON array; there is no paginated envelope here) and GET /patents/{patentId}/events/{eventId}.
• Across the portfolio: GET /patent-events answers "what falls due in this window" and is the workhorse of a monthly integration cycle.

eventType is an open enum

RENEWAL is the only kind today, but new kinds will be added over time. Ignore events whose kind you do not handle (see conventions). Each event also carries a duePeriod urgency bucket (UPCOMING, CURRENT, LATE, GRACE_PERIOD, LAPSED) explained in events and due periods.

3. Fees are estimated

For each event, Renewr computes the expected cost live from its fee matrices and current exchange rates, converted into your invoice currency. The breakdown is fully visible, one component per line:

Component	What it covers
OFFICE	The patent office's official fee.
AGENT	The local agent's fee.
RENEWR	Renewr's service fee.
GRACE_PERIOD	The late surcharge, present only when paying inside the grace window.

Before an invoice exists, fees carry feesStatus: "ESTIMATED" and invoiceId: null. Amounts are decimal strings (e.g. "1250.00") in your invoice currency. Read them per event with GET /patents/{patentId}/events/{eventId}/fees, or inline on the period list by adding include=fees to GET /patent-events.

Because estimates are FX-converted, they move with exchange rates. For budget certainty you can freeze a month's rates with PUT /exchange-rate-freezes/{yearMonth}, as explained in fees and FX.

4. You instruct

For each due event, you tell Renewr what to do by posting to POST /patent-instructions with one of three decisions: PROCEED (pay this annuity), SKIP_THIS_TIME (handled outside Renewr this occurrence; the chain continues), or DROP (abandon the patent; terminal, all remaining future events are removed).

The instruction window opens on opensAt, the first day of the month two months before the due month (a dueDate of 2026-11-30 opens on 2026-09-01). Only the chronologically earliest un-instructed event of a patent can be instructed, so one POST batch can span many patents but only one event per patent per call. Every event tells you exactly where it stands via its instructability object. Check it before posting.

Instructions are final

Instructions run in DIRECT mode: they are executed immediately and synchronously inside the POST, and cannot be modified afterwards through the API. If you need to change an executed decision, contact the Renewr team.

The response is an instruction receipt, your proof of order, also downloadable as a PDF via GET /patents/{patentId}/events/{eventId}/documents/instruction-receipt. The full rules (windows, ordering, blocked reasons, error codes such as instruction_already_set and instruction_lapsed) are covered in instructions and instructability and the errors guide; the operational rhythm is in the monthly renewal cycle guide.

5. Renewr executes and pays

After a PROCEED, Renewr batches the payment to the office or local agent, confirms it, and records the office's official receipt. You observe progress through the event's processingStatus (with processingStatusUpdatedAt):

Status	Operational meaning
NOT_INSTRUCTED	Default at event creation, waiting for your decision.
INSTRUCTED	Your instruction was executed (set during the POST).
PAYMENT_SENT	The fee was included in a payment batch sent to the office/agent.
PAYMENT_CONFIRMED	The payment was confirmed received.
FULFILLED	The office's official receipt was recorded with no problem: the annuity is proven paid. Terminal happy state.
UNPROCESSABLE	The official-receipt stage recorded a problem (office rejection or complication). Terminal problem state. Renewr operators handle it; contact support.

Once an event reaches FULFILLED, the office's proof of payment is downloadable via GET /patents/{patentId}/events/{eventId}/documents/official-receipt.

Polling only

The API has no webhooks. Track status changes by polling: poll GET /patents/{patentId}/events/{eventId} for a specific event, and see syncing data for the recommended portfolio-wide pattern.

6. Invoicing and receipts

Renewr invoices you for executed renewals. An invoice aggregates many events across many patents; its fees[] lines reuse the exact fee shape from stage 3, each carrying eventId and patent: { id, providerId } back-references, so a single invoice fetch is self-sufficient, with no per-line lookups needed. Once invoiced, an event's fees flip to feesStatus: "INVOICED" with invoiceId set, and GET /patents/{patentId}/events/{eventId}/fees returns the billed amounts instead of the estimate.

Read invoices with GET /invoices and GET /invoices/{invoiceId}. Each invoice carries an origin (GENERATED, IMPORTED, or REGULARIZATION).

Three PDF documents exist per event, each downloadable once its stage is reached:

Document	Endpoint	Available when
Instruction receipt	…/documents/instruction-receipt	Your instruction was executed (stage 4).
Invoice	…/documents/invoice	The event has been invoiced (stage 6).
Official receipt	…/documents/official-receipt	The event is FULFILLED (stage 5).

Each returns 404 until the document exists. See downloading documents for streaming and filename details.

The lifecycle at a glance

Stage	What happens	What you call
1. Portfolio	Patents imported and synced by Renewr	GET /patents, GET /patents/{patentId}
2. Events computed	Each annuity becomes an event with a dueDate	GET /patents/{patentId}/events, GET /patent-events
3. Fees estimated	Live cost projection, ESTIMATED	GET …/events/{eventId}/fees, GET /patent-events?include=fees
4. You instruct	PROCEED / SKIP_THIS_TIME / DROP, executed immediately	POST /patent-instructions
5. Renewr executes	processingStatus progresses to FULFILLED	GET …/events/{eventId} (poll), GET …/documents/official-receipt
6. Invoicing	Fees become INVOICED; documents available	GET /invoices, GET /invoices/{invoiceId}, GET …/documents/invoice

Where to next

• Getting started: first authenticated call in five minutes.
• The monthly renewal cycle: the operational loop built on stages 2 to 4.
• Events and due periods: duePeriod, grace, and lapse in depth.
• Instructions and instructability: the full decision rules.
• Fees and FX: components, currencies, and rate freezes.
• Downloading documents: working with the three PDFs.
• Syncing data: keeping your system up to date without webhooks.