Invoices, documents & lookup

These recipes cover the read side of an integration: finding your data again, reconciling invoices line by line, pulling PDF documents, and reconstructing what happened on a patent. All amounts are decimal strings; compare them with a decimal library, never with floats.

I want to find a patent using my own reference. How?

Filter the patent list on providerId, the reference you supplied at import:

curl "https://api.renewr.example/api/v2/external/patents?providerId=ACME-2021-0042" \
  -H "x-api-key: $RENEWR_API_KEY"

{
  "pagination": { "totalItems": 1, "currentPage": 1, "itemsPerPage": 10, "totalPages": 1, "hasMore": false },
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "providerId": "ACME-2021-0042",
      "clientCaseReference": "P-0042-FR",
      "office": "EP",
      "status": "GRANTED"
    }
  ]
}

The match is exact, so you get at most one result. An unknown reference returns an empty page with status 200, never a 404, so check pagination.totalItems before reading data[0]. The id you extract here is the UUID every other endpoint expects in its path. See GET /patents and the identifier conventions in Getting started.

I want to check an invoice against my own records. How?

List your invoices, then fetch the one you want to reconcile:

# 1. The invoice list (paginated)
curl "https://api.renewr.example/api/v2/external/invoices?itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"

# 2. One invoice, with its full fee lines
curl "https://api.renewr.example/api/v2/external/invoices/c4a1b2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d" \
  -H "x-api-key: $RENEWR_API_KEY"

{
  "id": "c4a1b2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
  "reference": "INV-2026-0198",
  "origin": "GENERATED",
  "currency": "EUR",
  "totalIncludingTax": "1500.00",
  "hasPdfDocument": true,
  "fees": [
    {
      "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a",
      "patent": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "providerId": "ACME-2021-0042" },
      "total": "1250.00",
      "feesStatus": "INVOICED"
    }
  ]
}

Each invoice carries an origin (GENERATED, IMPORTED or REGULARIZATION) so you can route it in your bookkeeping. Every fees[] line carries its eventId and patent: { id, providerId }, so each line maps straight to your own reference with zero extra calls; compare each line's total (a decimal string) and the invoice totalIncludingTax against your records. See GET /invoices, GET /invoices/{invoiceId}, and Fees & exchange rates for the fee line shape.

I want the PDF of an invoice. How?

The invoice payload advertises its documents through hasPdfDocument and hasXlsxDocument. The download itself is per event: take a fees[] line's eventId and patent.id from the recipe above, then hit the event's invoice document:

curl -fOJ "https://api.renewr.example/api/v2/external/patents/7c9e6679-7425-40de-944b-e07fc1f90ae7/events/9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a/documents/invoice" \
  -H "x-api-key: $RENEWR_API_KEY"

The response is a binary application/pdf; -OJ saves it under the server-provided name (invoice-<eventId>.pdf from the Content-Disposition header) and -f makes curl exit non-zero on a 404 instead of saving an error body as a PDF. See GET .../documents/invoice and the full walkthrough in Downloading documents.

I want proof the annuity was actually paid at the office. How?

The official receipt is the office's own document, so it appears once Renewr has recorded it. Wait for the event's processingStatus to reach FULFILLED, then download:

# 1. Check the event status
curl "https://api.renewr.example/api/v2/external/patents/7c9e6679-7425-40de-944b-e07fc1f90ae7/events/9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a" \
  -H "x-api-key: $RENEWR_API_KEY"

# 2. Once processingStatus is FULFILLED, fetch the receipt
curl -fOJ "https://api.renewr.example/api/v2/external/patents/7c9e6679-7425-40de-944b-e07fc1f90ae7/events/9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a/documents/official-receipt" \
  -H "x-api-key: $RENEWR_API_KEY"

The route answers 404 until the document exists, so poll after FULFILLED and treat a 404 as "not yet" rather than an error. See GET .../documents/official-receipt, the status pipeline in The patent lifecycle, and Downloading documents for the download mechanics.

I want everything that is in the grace period right now. How?

There is no duePeriod query filter on GET /patent-events, so pull a past due window and filter client-side. Grace runs after dueDate, commonly for several months, so a window covering the past six months plus the current one catches everything:

curl "https://api.renewr.example/api/v2/external/patent-events?dueFrom=2026-01-01&dueTo=2026-07-31&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY" \
  | jq '[.data[] | select(.duePeriod == "GRACE_PERIOD")]'

{
  "patent": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "providerId": "ACME-2021-0042" },
  "dueDate": "2026-03-31",
  "duePeriod": "GRACE_PERIOD",
  "gracePeriodEndDate": "2026-09-30"
}

Keep the events whose duePeriod is GRACE_PERIOD; each one's gracePeriodEndDate tells you how long it remains recoverable. Paying in grace costs a surcharge, which shows up as the GRACE_PERIOD component when you add include=fees (see Fees & exchange rates). The bucket definitions live in Events & due periods.

I want the full renewal history of one patent. How?

One call returns every event of the patent, past and future, as a bare JSON array:

curl "https://api.renewr.example/api/v2/external/patents/7c9e6679-7425-40de-944b-e07fc1f90ae7/events" \
  -H "x-api-key: $RENEWR_API_KEY"

[
  {
    "id": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a",
    "dueDate": "2025-09-30",
    "renewal": { "annuityYear": 4 },
    "appliedDecision": "PROCEED",
    "processingStatus": "FULFILLED",
    "instructability": { "isAllowed": false, "blockedReason": "ALREADY_INSTRUCTED" }
  },
  {
    "dueDate": "2026-09-30",
    "renewal": { "annuityYear": 5 },
    "appliedDecision": null,
    "processingStatus": "NOT_INSTRUCTED",
    "instructability": { "isAllowed": true, "allowedDecisions": ["PROCEED", "SKIP_THIS_TIME", "DROP"] }
  }
]

Read the array chronologically by dueDate: appliedDecision plus processingStatus tell you what happened on each past event, and instructability tells you what can still be acted on. Note the shape: this endpoint returns the array directly, without the { pagination, data } envelope used by the list endpoints. See GET /patents/{patentId}/events and Instructions & instructability.

Related pages

• Downloading documents: all three per-event PDFs and their availability rules.
• Fees & exchange rates: the fee line shape shared by events and invoices.
• Getting started: authentication, identifiers, and your first calls.