API cookbook

Implement a self-serve lock extension flow

Customer-facing lock extension with policy validation, fee disclosure, and atomic state update.

RTBy RateStack TeamPublished2026-04-05Reviewed2026-04-05

intermediateTypeScript

// 1. Client requests an extension; server validates policy first
POST /v1/locks/{lockId}/extend
{
  "additionalDays": 7,
  "reason": "appraisal delay"
}

// Server response on success — atomic state update + journal entry
HTTP/1.1 200 OK
{
  "lockId": "...",
  "previousExpiry": "2026-05-15T17:00:00Z",
  "newExpiry": "2026-05-22T17:00:00Z",
  "extensionFee": 0.125,                // price hit in points
  "freeExtensionUsed": false,
  "journalEntryId": "...",
  "correlationId": "..."
}

// On policy violation — 422 with structured detail
HTTP/1.1 422 Unprocessable Entity
{
  "type": "https://api.ratestack.com/errors/lock-policy",
  "title": "Extension exceeds maximum",
  "detail": "Lock has been extended 14 days; max-extension is 14.",
  "violations": [
    { "field": "additionalDays", "code": "MAX_EXTENSION_EXCEEDED" }
  ]
}

Concurrency: optimistic locking on the lock row. Two simultaneous extension attempts result in one 200 and one 409 Conflict; the second client retries with the new state visible.

All recipes