You don't want to send the same parcel twice because of an internet issue or because someone clicked the 'send' button again. Idempotency Keys help prevent that.
Idempotency is a tough word to say and concept to explain, but we'll try our best here 😊
When you send a request with an idempotency key of xyz-abc attached, we record "xyz-abc key refers to this specific request". Then if we see a request with an idempotency key of xyz-abc again, with the same parameters, we re-send the response we sent for that original request, without applying the request again on our backend.
It's a way to make sure that your request doesn't get duplicated, even if your user clicks the "submit order" button again or refreshes the order page a few times. This is especially important when your request has consequences like booking a parcel delivery or otherwise putting a payment through.
An Example Order
Let's say that your user want to get a parcel delivered from Sydney to Brisbane. But the internet blinks out for a moment, and then they click the re-order button again because the request is taking a long time.
No Idempotency Key
Here's that order being submitted without an idempotency key:
Because we have no way to de-duplicate the requests, three orders end up getting created to send this parcel. And since we have no way to know that this is the same request being retried, the user will end up with three delivery drivers coming to their house and two leaving disappointed.
With an Idempotency Key
Here's that same order, but being submitted using an idempotency key:
Now, only one order has been created and the user won't get charged three times! And your software will receive the same (stored) response back with each request, so it knows the order was successful without any complex logic required.
Re-submitting too early
If your system submits a follow-up request with one of these keys too early – before the original request has been processed – then Sendle will return a HTTP 425 Too Early response.
Upon receiving this response, your system should wait a short while and then retry the exact same request.
Re-Submitting a Failed Order
You may submit an order and have it fail because, for example, the postcode was entered incorrectly.
If you want to then re-submit that order with a corrected postcode, you'll need to use a new idempotency key. That's because the old key refers to the original order request with the bad postcode.
This catches some people out, so keep it in mind while writing your implementation.
Let's Start Using Them!
Hopefully that gives you a good overview of what idempotency keys are and how they work.
On the next page we'll go through which endpoints support these keys and why.