Skip to content
SystemSyncer
Menu

Integration concept

What Is Idempotency?

What idempotency means, why it is essential for reliable integrations, which HTTP methods are idempotent, and the common ways to make create operations safe to retry.

Last reviewed:
Reading time
2 min read
By
Raúl Vaquerizo Tortosa

Short answer

An operation is idempotent if doing it several times has the same effect as doing it once. In integrations, idempotency is what makes retries safe — without it, a retry after a timeout can create a duplicate order or invoice. Integrations achieve it through upserts on natural keys, unique external references, and idempotency keys stored by the receiving system.

Idempotency means that repeating an operation does not change the result beyond the first time. Setting a light switch to “on” is idempotent: do it twice and the light is still on. Pressing a “toggle” button is not.

Why integrations need it

Networks fail in ambiguous ways. When a request times out, the client cannot know whether the server processed it. The only safe response is to retry — and the only way a retry is safe is if the operation is idempotent. Platforms that deliver events at least once, such as webhook systems, also create repeated inputs that must not produce repeated effects.

Idempotent and non-idempotent operations

RFC 9110 defines PUT, DELETE, and the safe methods (GET, HEAD, OPTIONS, TRACE) as idempotent. POST and PATCH are not idempotent by definition.

Operation Idempotent?
Set stock of SKU A at warehouse 1 to 42 Yes
Add 5 to stock of SKU A No
Create order for external ID 1234 if not exists Yes
Create a new order No
Mark order 1234 as shipped Yes
Send shipping email No (unless deduplicated)

How to make operations idempotent

  1. Prefer absolute over relative updates. “Set to 42” instead of “add 5.”
  2. Upsert by natural key. Create or update by SKU, external ID, or another stable key.
  3. Unique external references. Store the source system’s ID on the target record and enforce uniqueness.
  4. Idempotency keys. Send a key with each non-idempotent request; the server stores it with the result and returns the same result for repeats. The IETF has an Internet-Draft for a standard Idempotency-Key header, and Shopify’s GraphQL Admin API uses an @idempotent directive on supporting mutations.

The key must be deterministic per logical operation — the same on every retry. A fresh random key per attempt provides no protection.

Summary

Idempotency makes repeated operations harmless, which is what makes retries, at-least-once delivery, and replay safe. Use absolute updates, upserts, unique external references, and stable idempotency keys. For implementation details, see how to implement retries and idempotency.

Frequently asked questions

Is GET always idempotent?

According to RFC 9110, GET is a safe method and therefore idempotent. In practice, a badly designed API could still have side effects on GET; well-designed APIs do not.

Is idempotency the same as deduplication?

They are related. Deduplication discards repeated inputs; idempotency ensures that repeated inputs produce no extra effects. Idempotent processing makes deduplication failures harmless.

Does an idempotency key have to be a UUID?

No, any unique string works unless the API requires a format. What matters is that the key is the same on every retry of the same logical operation.

Sources and further reading

Platform-specific statements on this page were checked against these sources on . Vendor APIs change; confirm details in the current documentation before you build.

  1. [1] RFC 9110: HTTP Semantics — idempotent methods — IETF
  2. [2] The Idempotency-Key HTTP header field (Internet-Draft) — IETF HTTPAPI Working Group
  3. [3] Shopify idempotent requests — Shopify

Related reading