Estimates & budgeting

Every recipe on this page uses GET /patent-events with include=fees: it returns the renewal events due in a window, each carrying its estimated fee breakdown (feesStatus: "ESTIMATED"). Amounts are decimal strings in your invoice currency; sum them with a decimal library, never with floats. Estimates follow exchange rates and fee schedules, so re-fetch them when you need current numbers rather than caching them.

I want an estimate for the next three months. How?

Ask for the window with dueFrom and dueTo (both inclusive), and include the fees:

curl "https://api.renewr.example/api/v2/external/patent-events?dueFrom=2026-08-01&dueTo=2026-10-31&include=fees&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"

Each event in data[] carries its estimate:

{
  "dueDate": "2026-09-30",
  "patent": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "providerId": "ACME-2021-0042" },
  "renewal": { "annuityYear": 5 },
  "fees": {
    "feesStatus": "ESTIMATED",
    "currency": "EUR",
    "total": "1250.00",
    "components": [
      { "type": "OFFICE", "amount": "800.00" },
      { "type": "AGENT", "amount": "150.00" },
      { "type": "RENEWR", "amount": "300.00" }
    ]
  }
}

Your estimate for the period is the sum of fees.total, grouped by fees.currency. Walk the pages with currentPage until pagination.hasMore is false (the server caps itemsPerPage at 100).

Whole months

For a single month, dueMonth=2026-10 is a shortcut for dueFrom=2026-10-01&dueTo=2026-10-31.

I want the same estimate, but only for the owner "Safran". How?

Add the owners filter:

curl "https://api.renewr.example/api/v2/external/patent-events?dueFrom=2026-08-01&dueTo=2026-10-31&owners=Safran&include=fees&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"

The value must match the owner field of your patents as it appears in your portfolio data (check it on GET /patents). The parameter is repeatable to cover several owners at once:

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

The same pattern works for offices (patent authorities: EP, US, JP...) and family (your family references).

I want the estimated cost of one specific patent's next renewal. How?

Resolve the patent from your own reference, then read the fees of its next event:

# 1. Your reference to the Renewr patent id
curl "https://api.renewr.example/api/v2/external/patents?providerId=ACME-2021-0042" \
  -H "x-api-key: $RENEWR_API_KEY"

# 2. The patent's events (pick the next un-instructed one by dueDate)
curl "https://api.renewr.example/api/v2/external/patents/$PATENT_ID/events" \
  -H "x-api-key: $RENEWR_API_KEY"

# 3. Its fee breakdown
curl "https://api.renewr.example/api/v2/external/patents/$PATENT_ID/events/$EVENT_ID/fees" \
  -H "x-api-key: $RENEWR_API_KEY"

GET .../events/{eventId}/fees answers for every event: projected amounts while the event is un-invoiced (feesStatus: "ESTIMATED"), billed amounts afterwards (feesStatus: "INVOICED").

I want October's estimate to stop moving with exchange rates. How?

Freeze the month (the capability must be enabled for your account):

curl -X PUT "https://api.renewr.example/api/v2/external/exchange-rate-freezes/2026-10" \
  -H "x-api-key: $RENEWR_API_KEY"

From then on, every estimate for events due in October is computed with the captured rates and reports isFxRateFrozen: true: the FX part of the price you see is the price you will be invoiced. The PUT is idempotent, so retrying it never re-captures new rates. Details in Fees & exchange rates.

I want the estimate broken down by office. How?

Either query one office at a time with the offices filter, or pull the whole window once and group client-side. Note that the event payload itself carries no office field: it references its patent as patent: { id, providerId }, so client-side grouping means joining events to the patents you already listed via GET /patents (whose payload does carry office). For a quick single-office number:

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

Related pages

• The monthly renewal cycle: the full decide-and-instruct loop these estimates feed into.
• Fees & exchange rates: the fees object, components, and freeze semantics.
• Keeping data in sync: why estimates should be re-fetched rather than cached.