AI & autonomy
Idempotency key
A stable identifier attached to a write request so retrying the same intended action does not create a second external effect.
Glossary
AI & autonomy
Primary references on this page:
·
QuickBooks Online: request IDs and idempotenceAn idempotency key tells a receiving system that two matching requests represent one intended action. It matters when a property-management app sends a payment, bill, message, lease update, or vendor dispatch and loses the response. Without a stable identity, an automatic retry can look like a brand-new instruction.
The control artifact is an idempotency record that binds the key to the action type, property or account scope, request fingerprint, first-attempt time, current state, and provider receipt. A key should not be reused for a different amount, tenant, invoice, or payload. A matching key is evidence of identity, not proof that the external action ultimately settled.
Suppose a landlord approves one $425 plumbing invoice. The PMS submits the payment, but the connection times out after the processor accepts it. A safe retry uses the original key and first checks the stored or provider-side result. Generating a second key could pay the invoice twice; merely marking the local task complete could hide an unpaid bill.
When evaluating an integration, ask which writes accept provider-enforced idempotency, how long keys are retained, what happens when the same key arrives with changed parameters, and how ambiguous results are reconciled. If the vendor can only say that its button is disabled after one click, duplicate protection is not yet demonstrated.
What the record must preserve
Retain the intended action, stable key, payload fingerprint, attempt history, provider object ID, response state, and reconciliation result. The property ledger should link to the receipt rather than treating the key itself as confirmation.
Failure modes to test
Test a dropped response after provider acceptance, two simultaneous requests, and reuse of a key with a changed payload. The integration should return the prior result or block the conflict without creating another charge or record.