Instructing & tracking

Every recipe on this page revolves around POST /patent-instructions and the instructability object that every patent event carries. Instructions run in DIRECT mode: they execute immediately and synchronously inside the POST, and they are immutable through the API afterwards. Read instructability before you send, and treat every POST as final. Details in Instructions & instructability.

I want to renew everything due in October. How?

List the month, keep the instructable events, instruct them in one batch:

bash

# 1. Everything due in October, with its instructability
curl "https://api.renewr.example/api/v2/external/patent-events?dueMonth=2026-10&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"

Keep the events where instructability.isAllowed is true and "PROCEED" appears in instructability.allowedDecisions, then send one PROCEED entry per event:

bash

# 2. One PROCEED per event (each event belongs to a different patent)
curl -X POST "https://api.renewr.example/api/v2/external/patent-instructions" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": [
      { "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a", "decision": "PROCEED" },
      { "eventId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "decision": "PROCEED" }
    ]
  }'

The 201 response is an instruction receipt covering the whole batch (see proof of instruction). GET /patent-events is the workhorse here; the full monthly loop is described in The monthly renewal cycle.

One event per patent, all or nothing

A batch may span many patents, with one event per patent per call: only the chronologically earliest un-instructed event of a patent is instructable, so a second event of the same patent in the same batch is rejected. Batches are all or nothing: one rejected entry rolls the whole batch back. If a retry answers 409 instruction_already_set for an event, that event already carries a decision from an earlier run; treat it as success, remove the entry, and resend the rest.

We pay one annuity ourselves this year, how do I tell Renewr?

Send SKIP_THIS_TIME on that annuity's event:

bash

curl -X POST "https://api.renewr.example/api/v2/external/patent-instructions" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": [
      { "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a", "decision": "SKIP_THIS_TIME" }
    ]
  }'

Renewr records this occurrence as handled outside Renewr and pays nothing for it. The decision applies to this event only: all future events of the patent are kept, and the next annuity will come up for instruction as usual. See the decision table in Instructions & instructability.

I want Renewr to stop renewing a patent for good. How?

Find the patent's earliest un-instructed event, then send DROP on it:

bash

# 1. The patent's events (a bare JSON array, no pagination envelope)
curl "https://api.renewr.example/api/v2/external/patents/7c9e6679-7425-40de-944b-e07fc1f90ae7/events" \
  -H "x-api-key: $RENEWR_API_KEY"

# 2. DROP the one event where instructability.isAllowed is true
curl -X POST "https://api.renewr.example/api/v2/external/patent-instructions" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": [
      { "eventId": "9f0d1e7a-3b2c-4d5e-8f6a-7b8c9d0e1f2a", "decision": "DROP" }
    ]
  }'

GET /patents/{patentId}/events returns every event with its instructability; the ordering rule guarantees that at most one event is instructable at a time, and that is the one to drop.

DROP is irreversible

Executing a DROP deletes all remaining future events of the patent. The chain ends there, no further annuity will be presented, and the right will lapse at the office. There is no undo through the API.

Why can't I instruct this event?

Fetch the event and read its instructability:

bash

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"

json

{
  "dueDate": "2026-10-31",
  "instructability": {
    "isAllowed": false,
    "allowedDecisions": [],
    "blockedReason": "TOO_EARLY",
    "opensAt": "2026-08-01",
    "mode": "DIRECT"
  }
}

`blockedReason`	Meaning	What to do
`ALREADY_INSTRUCTED`	The event already carries a decision.	Nothing; check `appliedDecision` for what was decided.
`TOO_EARLY`	The instruction window opens at `opensAt`, the first day of the month two months before the due month (here `dueDate` 2026-10-31 opens on 2026-08-01).	Wait until `opensAt`, then instruct.
`EARLIER_EVENT_PENDING`	An older un-instructed event of the same patent is still waiting for a decision.	Instruct the patent's earliest un-instructed event first.

There is a fourth situation with isAllowed: true: on a lapsed event, PROCEED disappears from allowedDecisions and only SKIP_THIS_TIME and DROP remain, because the office no longer accepts the payment. Sending PROCEED anyway fails with 422 instruction_lapsed. The golden rule: only ever send a decision listed in allowedDecisions, and the POST will succeed. Error codes are catalogued in Errors.

I want proof of the instruction I just sent. How?

The 201 response of POST /patent-instructions is the receipt:

json

{
  "object": "instructionReceipt",
  "reference": "IR-2026-0123",
  "number": 123,
  "issueDate": "2026-07-22",
  "instructions": [
    {
      "object": "instruction",
      "id": "3e2f1a0b-9c8d-4e7f-a6b5-c4d3e2f1a0b9",
      "decision": "PROCEED",
      "status": "EXECUTED",
      "executedAt": "2026-07-22T09:14:03.000Z"
    }
  ]
}

Store reference and issueDate in your audit trail; each entry's status: "EXECUTED" confirms the decision was applied during the call. The same receipt exists as a PDF per event:

bash

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

-OJ saves the file under its server-provided name (instruction-receipt-<eventId>.pdf) and -f turns a 404 into a non-zero exit while the PDF is still being generated. See GET .../documents/instruction-receipt and Downloading documents.

I want to follow what happens after I instruct. How?

Poll the event and read processingStatus:

bash

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"

json

{
  "appliedDecision": "PROCEED",
  "processingStatus": "PAYMENT_SENT",
  "processingStatusUpdatedAt": "2026-07-20T14:02:11.000Z"
}

After a PROCEED, GET .../events/{eventId} shows the pipeline advancing: INSTRUCTED, then PAYMENT_SENT, then PAYMENT_CONFIRMED, then FULFILLED. At FULFILLED the office's official receipt is recorded and its PDF becomes downloadable at GET .../documents/official-receipt, which is your proof the annuity was actually paid. UNPROCESSABLE signals a problem recorded at the office-receipt stage; Renewr operators are on it, so contact the Renewr team. Compare processingStatusUpdatedAt with the value from your previous poll to detect changes cheaply.

The monthly renewal cycle: the full list, decide, instruct, track loop these recipes belong to.
Instructions & instructability: decisions, the ordering rule, and the instructability object in depth.
Errors: every problem code the instruction endpoint can answer with.

Instructing & tracking ​

I want to renew everything due in October. How? ​

We pay one annuity ourselves this year, how do I tell Renewr? ​

I want Renewr to stop renewing a patent for good. How? ​

Why can't I instruct this event? ​

I want proof of the instruction I just sent. How? ​

I want to follow what happens after I instruct. How? ​

Related pages ​

Instructing & tracking

I want to renew everything due in October. How?

We pay one annuity ourselves this year, how do I tell Renewr?

I want Renewr to stop renewing a patent for good. How?

Why can't I instruct this event?

I want proof of the instruction I just sent. How?

I want to follow what happens after I instruct. How?

Related pages