diff --git a/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md b/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md
new file mode 100644
index 00000000..57084239
--- /dev/null
+++ b/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md
@@ -0,0 +1,13 @@
+---
+title: Payment Idempotency Keys
+summary: "Always pass an idempotency key when calling the payment provider to safely retry authorizations."
+topics: [gotchas, payments]
+files:
+  - src/payments.ts
+---
+
+# Payment Idempotency Keys
+
+When retrying an authorization request with the payment provider, it is critical to use an idempotency key. This ensures that the payment provider will not charge the customer twice if the first request succeeded but we timed out while waiting for the response.
+
+Agents editing [[src/payments.ts]] should ensure that any calls to the provider include an idempotency key generated at the beginning of the checkout session.
diff --git a/examples/sample-repo/src/payments.ts b/examples/sample-repo/src/payments.ts
index 60b4399b..ad8d1091 100644
--- a/examples/sample-repo/src/payments.ts
+++ b/examples/sample-repo/src/payments.ts
@@ -1,7 +1,7 @@
-export async function authorizePayment(amountCents: number): Promise<string> {
+export async function authorizePayment(amountCents: number, idempotencyKey?: string): Promise<string> {
   if (amountCents <= 0) {
     throw new Error("amountCents must be positive");
   }
 
-  return "receipt_sample";
+  return "receipt_sample_" + (idempotencyKey || "none");
 }