Freeze a month (idempotent)

PUT /api/v2/external/exchange-rate-freezes/{yearMonth}

Authentication: x-api-key header, with the exchange-rate-freezes:write scope. See Authentication and limits.

Freezes the exchange rates for the given month and returns the affected renewal events. Idempotent.

Path parameters

Name	Type	Required	Description
yearMonth	string	Yes	Target month, YYYY-MM.

Response

200 The freeze of the month.

{
  "object": "exchangeRateFreeze",
  "yearMonth": "2026-10",
  "events": [
    {
      "object": "frozenRateEvent",
      "clientCaseReference": "P-2021-0042-EP",
      "dueDate": "2026-10-31",
      "amount": "800.00",
      "currency": "EUR",
      "isFxRateFrozen": false,
      "hasInstruction": false
    }
  ]
}

Response fields

Field	Type	Description
object	string	String describing the object type (auto-description). One of: exchangeRateFreeze.
yearMonth	string	Frozen month, YYYY-MM.
events	array of objects	Renewal events affected by the freeze.
events[].object	string	String describing the object type (auto-description). One of: frozenRateEvent.
events[].clientCaseReference	string or null	Client case reference of the IP right.
events[].dueDate	string	Renewal / annuity due date of the event.
events[].amount	string	Total renewal fees in the event currency (decimal string).
events[].currency	string	ISO 4217 currency code of the event.
events[].isFxRateFrozen	boolean	True when the FX rate for this event is frozen.
events[].hasInstruction	boolean	True when an instruction has already been given for this event.

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).
429	Daily API call limit exceeded (rate_limit_exceeded): the Retry-After header gives the seconds until reset.

Example request

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