Idempotency in API Integrations: How to Stop Duplicate Orders

Idempotency in API Integrations: How to Stop Duplicate Orders

08 Nov, 2026
14 min read

Idempotency stops a repeated API message from creating a second order, charge or booking. Messages get sent twice for ordinary reasons. A request times out and the sender tries again, or a webhook provider sends the same event twice. If the receiving system cannot tell the repeat from a new request, it creates that second record, and the customer sees it.

This guide is for engineering leads and product owners. It covers orders, payments and bookings that move through APIs, webhooks or queues. Our comparison of API integration types covers how those ways of connecting systems differ.

What is idempotency?

Idempotency means that doing the same operation twice has the same effect as doing it once. In an API integration, a "create order" request that arrives twice still leaves one order in the system. The second request can get a reply, but it changes nothing. HTTP defines idempotent methods the same way in RFC 9110, section 9.2.2.

Reads are easy to make idempotent, because looking at an order twice changes nothing. The hard cases are writes that move money, stock or a calendar slot. We recommend treating each of those writes as unsafe to repeat until the receiving system can show how it recognises a repeat.

Why do integrations send the same message twice?

Messages repeat when a lost response or a timeout makes the sender retry, and when a webhook provider sends an event again. Events can also arrive out of order.

The first case is a lost response. The receiving system creates the order, but the reply never reaches the sender, or the call times out first. To the sender this looks like a failure, so it retries. RFC 9110 describes this exact case. Under section 9.2.2, an idempotent request "can be repeated automatically if a communication failure occurs before the client is able to read the server's response." The same retry on a request that is not idempotent creates a second order.

Stripe resends events on its own, without any action from the receiver. Stripe's webhook documentation states that "Webhook endpoints might occasionally receive the same event more than once." In live mode, Stripe retries a failed delivery for up to three days with exponential backoff.

With GitHub, the repeat starts on the receiving side. Its page on handling failed webhook deliveries states that "GitHub does not automatically redeliver failed webhook deliveries." GitHub's webhook guidance asks for a 2XX response within 10 seconds. It also advises the receiving team to redeliver missed webhooks once their server is back up after downtime. A redelivery carries the same X-GitHub-Delivery value as the original. The receiver can use it to skip events it handled before the outage.

Events can also arrive in the wrong order, because Stripe does not guarantee to deliver them in the order they are generated (Stripe webhooks). A receiver can see a later event before an earlier one.

A vendor may say that its API "handles retries". Those retries are one source of the repeats, so the duplicate check has to run in the system that receives the message.

What a repeated or lost message costs the business

Each duplicate turns one sale, payment or booking into two, and each dropped message turns it into none. In an order or payment flow, the damage looks like this:

  • an order that the warehouse picks and ships twice
  • a customer charged twice for one checkout, then a refund and a support ticket
  • two bookings accepted for the same host and time
  • a journal entry posted twice, which leaves the books out of line with the bank until payment reconciliation flags the extra entry for reversal
  • stock reduced twice, so the store shows an item as sold out while it is still on the shelf
  • an order or payment update that never arrives, with nobody alerted

Our retail and ecommerce integrations detect duplicate marketplace orders.

Some teams see this work as over-engineering for their volume. The causes are timeouts and redeliveries, and those happen at any volume. A smaller integration sees fewer repeats, but each one still costs a refund, a manual fix or a call from an unhappy customer.

How does an idempotency key work?

An idempotency key is a unique value that the client sends with a write request. The server stores the first result under that key and returns that same result for any retry that carries it.

Stripe's API reference puts the purpose in one line. The API "supports idempotency for safely retrying requests without accidentally performing the same operation twice" (Stripe idempotent requests). The steps below follow Stripe's documented behaviour for API v1. The same shape works for an internal API.

  1. The client creates one key for one business operation, such as one checkout, before the first attempt. Stripe suggests V4 UUIDs and accepts keys up to 255 characters long.
  2. The client sends the key with the request.
  3. The server looks up the key. For a new key, it runs the operation and stores the result with the key.
  4. A retry with the same key gets the stored result, and no second order or charge is created.
  5. A request that reuses the key with different data is rejected. Stripe compares the new parameters with the original request and returns an error when they differ.
  6. Keys expire after a set time. For API v1, Stripe can remove keys once they are at least 24 hours old. A key used again after that starts a new request.

The key must stay the same across every retry of one operation. A client that makes a fresh key for each attempt gets no protection, because each attempt looks new to the server. For that reason the key is created at the start of the business operation, before any network call. It is saved with the operation, so a retry after a crash can find it.

The IETF is working on a shared header for the key. Its document The Idempotency-Key HTTP Header Field (draft-ietf-httpapi-idempotency-key-header-08, dated 22 October 2026) is an active Internet-Draft intended for the Standards Track. As of 13 November 2026 it has not been published as an RFC.

How should retries work?

A retry is safe only when the call is idempotent. Each retry should wait longer than the one before, with some randomness in the wait, and the attempts should stop at a fixed limit.

The AWS Builders' Library article Timeouts, retries and backoff with jitter states the first rule plainly: "In general, our view is that APIs with side effects aren't safe to retry unless they provide idempotency."

Exponential backoff means the wait grows after each failure, for example from one second to two, then four. Jitter "adds some amount of randomness to the backoff to spread the retries around in time," in the article's words. Without jitter, clients that failed together come back together and hit the struggling service at the same moment.

Stacked retries multiply the load on the services below them. The article shows this with a worked example, which is arithmetic and not a measured average. A request passes through five layers of services with three retries at each layer. If each layer retries on its own, the load on the database rises 243x. The same multiplication applies to any stack where every layer retries.

The same article gives AWS's best practice for low-cost operations, which is to retry "at a single point in the stack". We recommend letting the other layers fail fast, so that one failure does not become many calls. Some errors will fail the same way on every attempt, such as a request rejected for bad data. Those skip the retries and go straight to the dead-letter queue.

What is a dead-letter queue?

A dead-letter queue is a separate queue that holds messages a consumer could not process after a set number of attempts. Each failed message keeps its original content, so an engineer can find out why it failed and send it back after a fix. The main queue keeps moving while the failed message waits.

Amazon SQS shows how this works in one service. A redrive policy sets a value called maxReceiveCount. AWS defines it as "the number of times a consumer can receive a message from a source queue before it is moved to a dead-letter queue." With a value of 1, a single failure moves the message aside, so AWS advises a value high enough to allow for sufficient retries. SQS calls the return trip a redrive, which moves messages out of the dead-letter queue so they can be processed again.

Two SQS details matter for order and payment flows. AWS advises against a dead-letter queue on a FIFO queue when the exact order of messages must hold. Moving one message aside breaks the sequence. On standard queues, a message keeps its original enqueue time when it moves. AWS therefore recommends a longer retention period on the dead-letter queue than on the source queue. Otherwise a parked message can expire before anyone reviews it.

Replay is safe only when the consumer is idempotent. A message that partly succeeded before it failed will run again on replay. The duplicate check is what stops the finished part from happening twice.

At-most-once, at-least-once or exactly-once: which do you need?

Order and payment flows usually need at-least-once delivery, paired with an idempotent consumer that ignores repeats. That pairing gives the business result people usually mean when they ask for exactly-once.

Delivery guarantee What it means What it means for an order What to add
At-most-once Each message is sent once and never retried An order can be lost, and no one is told Reconciliation to find the gaps. Rarely acceptable for orders or payments
At-least-once The sender retries until the receiver confirms No order is lost, but the same order can arrive twice An idempotent consumer with a key or event ID check, plus a dead-letter queue
Exactly-once Each message takes effect one time One order per checkout In practice, at-least-once delivery plus an idempotent consumer, so each message is processed effectively once

When a vendor promises exactly-once delivery, the next question is where its duplicate check runs. A second question is what happens if the receiver's own database write fails after the message is marked as done.

How one webhook moves from receipt to replay

A safe webhook handler replies fast and does the real work later from a queue. The worker skips any event it has already processed and parks failures in a dead-letter queue for replay. The steps below use a payment event as the example.

  1. The endpoint receives the event and checks the signature the provider sends. A request that fails the check is rejected, so a forged event never reaches the queue.
  2. It returns a 2xx response straight away. Stripe tells integrators to "return a 200 response before updating a customer's invoice as paid in your accounting system" (Stripe webhooks). A slow reply looks like a failure to the provider and brings one more delivery.
  3. The endpoint puts the raw event on a queue.
  4. A worker reads the event and checks its ID against a table of processed IDs. Stripe's guidance is to log the event IDs already processed and skip any event that is already logged. For GitHub, the X-GitHub-Delivery value plays the same role.
  5. The worker checks the current state of the record before it acts, because events can arrive out of order. An older status update must not overwrite a newer one.
  6. It saves the business change and the event ID in one database transaction. Either both are saved or neither is, so a crash between the two cannot leave a paid invoice with no record of the event.
  7. If processing fails, the worker retries with exponential backoff and jitter, up to a fixed limit.
  8. After the last attempt, the event moves to the dead-letter queue with its original body and the error.
  9. An engineer fixes the cause and replays the event. The ID check in step 4 makes the replay safe.

Steps 2 and 3 keep the provider from retrying a slow reply. Steps 4 to 6 stop duplicates, and steps 7 to 9 stop silent loss.

What to ask an integration vendor or partner

Proof comes from a design document, or from a test run in which the same request sent twice leaves one record. A vendor with a safe integration can show either one. These eight questions test the claim:

  • Does every write that creates an order, a charge or a booking carry an idempotency key or an event ID check?
  • Where are keys and stored results kept, and do they last longer than the longest retry window?
  • What is the retry policy, meaning which errors are retried, how long each wait is and when retries stop?
  • Which one layer retries, so that retries do not multiply down the stack?
  • Does the dead-letter queue keep the original message and the error, and is there a tool to replay messages after a fix?
  • Which flows need strict order, and how are out-of-order events handled?
  • Who receives the alert when messages fail or the dead-letter queue grows, and who responds?
  • Is there a test that sends the same request twice and confirms that one record results?

Our API integration and development service includes "idempotency, ordering, replay and dead-letter handling". Its monitoring alerts the agreed support team when syncs fail.

Where these patterns appear in our case studies

Several case studies on our site describe these controls at the design level.

  • Multichannel commerce order management: each request brings an idempotency key, which lets the backend recognise a repeat.
  • Transport and freight management: the financial update, the journal write and the queued accounting sync share one database transaction. A source idempotency key keeps the journal safe from a duplicate posting.
  • Appointment booking platform: the start, end and host form a UUIDv5 idempotency key, and a database uniqueness rule is the final guard for the same host and time.
  • Usage event processing: failures follow their policy into a dead-letter topic that keeps the original event and an error code. Operators can then inspect the failed input instead of rebuilding it from a status message.
  • Payment provider orchestration: each retry raises the attempt count and records the next run time, so an operator can tell a pending payment from an undelivered merchant webhook.

Frequently asked questions

Is POST idempotent?

HTTP leaves POST off its list of idempotent methods. RFC 9110 gives that list as PUT, DELETE and the safe methods such as GET. Most "create" calls use POST, so they need another way to spot a repeat. A client-sent idempotency key does this, as does a key built from the request data with a uniqueness rule behind it.

Is PUT idempotent?

PUT is idempotent under RFC 9110, because sending the same full replacement twice leaves the resource in the same state. That holds only when the server treats PUT as a true replacement. A handler that sends an email or adds a fee on every PUT breaks the promise, even though the method is idempotent on paper.

How long should idempotency keys be kept?

Keys should outlast the latest retry that can still arrive, a window the sender's retry policy sets. Stripe retries live-mode webhook deliveries for up to three days, so a record of processed Stripe event IDs must last longer, with room for a manual replay. A key that expires sooner lets a late repeat through as a new request.

What is the difference between exactly-once delivery and idempotency?

Delivery counts how many times a message arrives, while idempotency counts how many times it takes effect. An at-least-once queue can deliver the same order message twice. With an idempotent consumer, the second copy finds its event ID already recorded and creates nothing, so the business still sees one order.

Does a dead-letter queue lose data?

A dead-letter queue keeps failed messages, but they can still expire or sit unnoticed. Messages there stay subject to the queue's retention setting, so the oldest ones age out if nobody acts. A written replay procedure, including a check that the fix works before the redrive, keeps a parked message from turning into a lost one.

Planning an integration that moves orders or payments

If orders, payments or bookings already move between your systems, a discovery call is the place to start. It covers those systems and the flows that carry money, stock or appointments. Most projects start with a two-week integration audit.

Buttons: "Book a Technical Discovery Call" → /contact · "Get a Project Estimate" → /project-estimate

Tags:

Share:

Saqib Tasneem
Founder & CEO, Vortex Web Innovate

Saqib Tasneem

Saqib Tasneem is the founder and CEO of Vortex Web Innovate, a software and web development company in Easthampton, Massachusetts. He has more than 10 years of experience across technology, taxation, accounting, retail operations and business development, and leads the delivery of custom software, ERP and enterprise systems, web and mobile apps, cloud and DevOps, and AI solutions. He holds an MBA from Government College University, Lahore.

Working on this yourself?

Tell us what you're trying to build or fix. If it isn't a fit, we'll say so on the first call.

Book a Technical Discovery Call

Related work

FHIR Integration for Clinical Data: Access Policies and a Local Message Queue

A FHIR-based application backend with record access policies, version history and links to existing clinical systems.

Read the case study

Long-Running Workflow Automation and API Integration

A visual workflow platform that saves execution progress, waits for external input and resumes work from its recorded state.

Read the case study

Payment Orchestration: Provider Routing with Recoverable Follow-Up Work

A shared payment interface with provider selection, status tracking and scheduled recovery work.

Read the case study
Industries

Industries we serve

Healthcare & Life Sciences

EHR integration, HL7/FHIR, telehealth, clinical workflow, PHI handling

Explore this industry

Financial Services & FinTech

Payments, reconciliation, risk models, audit trails

Explore this industry

Something on your own site not working?

Tell us what you're trying to build or fix. We'll put someone on the call who can actually assess it - and if it's not a fit, we'll tell you on the first call rather than the third.