docs: added idempotency key documentation (#4039)

docs/content/modules/carts-and-checkout/backend/cart-completion-strategy.md

@@ -90,7 +90,7 @@ The cart completion strategy is required to implement a single method: the `comp
 The method accepts three parameters:
 
 - `cartId`: the first parameter of the method, which is a string indicating the ID of the cart to complete.
-- `idempotencyKey`: the second parameter of the method, which is an instance of the `IdempotencyKey` entity. The idempotency key is retrieved based on the idempotency key passed in the header of the request, and it’s used to determine the current point reached in the checkout flow to avoid inconsistencies on interruptions. You can learn more about the idempotency key [here](../cart.md#idempotency-key).
+- `idempotencyKey`: the second parameter of the method, which is an instance of the `IdempotencyKey` entity. The idempotency key is retrieved based on the idempotency key passed in the header of the request, and it’s used to determine the current point reached in the checkout flow to avoid inconsistencies on interruptions. You can learn more about the idempotency key [here](../cart.md#idempotency-key). You can also learn how to use it within your strategy by following [this guide](../../../development/idempotency-key/use-service.md)
 - `context`: the third parameter of the method, which is an object that holds a single property `ip`. `ip` is a string indicating the IP of the customer.
 
 The completion strategy is expected to return an object with the following properties:

docs/content/modules/carts-and-checkout/cart.md

@@ -67,13 +67,9 @@ You can initiate the cart completion process by sending a request to the [Comple
 
 ### Idempotency Key
 
-An Idempotency Key is a unique key associated with a cart. It is generated when the cart completion process is started. The idempotency key is stored in the Cart entity under the attribute `idempotency_key`.
+An Idempotency Key is a unique key associated with a cart. It is generated when the cart completion process is started and can be used to retry cart completion safely if an error occurs. The idempotency key is stored in the Cart entity under the attribute `idempotency_key`.
 
-That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
-
-The backend wraps essential parts of the checkout completion in its own step and stores the current step (known as recovery point) of checkout with its associated Idempotency Key.
-
-Then, if the request is interrupted for any reason or an error occurs, the client can retry completing the checkout using the Idempotency Key, and the flow will continue from the last stored step.
+You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
 
 ### Cart Completion Process
 

docs/content/modules/carts-and-checkout/payment.md

@@ -130,17 +130,11 @@ Additionally, `Payment` has the `captured_at` date-time attribute which is fille
 
 ## Idempotency Key
 
-An Idempotency Key is a unique key associated with a cart. It is generated at the last step of checkout before authorization of the payment is attempted.
+An Idempotency Key is a unique key associated with a cart. It is generated at the last step of checkout before authorization of the payment is attempted and used in the request and response header.
 
-That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
+If the request is interrupted for any reason or the payment fails, the client can retry completing the check out using the Idempotency Key, and the flow will continue from the last stored step. This prevents any payment issues from occurring with the customers and allows for secure retries of failed payments or interrupted connections.
 
-If an error occurs or the purchase is interrupted at any step, the client can retry the payment by adding the Idempotency Key of the cart as the `Idempotency-Key` header field in their subsequent requests. 
-
-The backend wraps each essential part of the checkout completion in its own step and stores the current step of checkout with its associated Idempotency Key. 
-
-If then the request is interrupted for any reason or the payment fails, the client can retry completing the check out using the Idempotency Key, and the flow will continue from the last stored step.
-
-This prevents any payment issues from occurring with the customers and allows for secure retries of failed payments or interrupted connections.
+You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
 
 ---
 

docs/content/modules/orders/claims.md

@@ -36,13 +36,9 @@ You can create a claim either using the [Create Claim endpoint](/api/admin#tag/O
 
 ### Idempotency Key
 
-An Idempotency Key is a unique key associated with a claim. It is generated when the claim creation process is started by the admin using the Create Claim endpoint. The idempotency key is stored in the `ClaimOrder` entity in the attribute `idempotency_key`.
+An Idempotency Key is a unique key associated with a claim. It is generated when the claim creation process is started by the admin using the [Create Claim endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderClaims) and can be used to retry the claim creation safely if an error occurs. The idempotency key is stored in the `ClaimOrder` entity in the attribute `idempotency_key`.
 
-That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
-
-The backend wraps essential parts of the claim creation process in its own step and stores the current step (known as recovery point) of the process with its associated Idempotency Key.
-
-Then, if the request is interrupted for any reason or an error occurs, the client can retry creating the return using the Idempotency Key, and the flow will continue from the last stored step.
+You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
 
 ### Create Claim Endpoint Process
 

docs/content/modules/orders/returns.md

@@ -42,13 +42,9 @@ Returns can be created in three ways:
 
 ### Idempotency Key
 
-An Idempotency Key is a unique key associated with a return. It is generated when the return creation process is started by the customer. The idempotency key is stored in the `Return` entity in the attribute `idempotency_key`.
+An Idempotency Key is a unique key associated with a return. It is generated when the return creation process is started by the customer and can be used to retry the return creation safely if an error occurs. The idempotency key is stored in the `Return` entity in the attribute `idempotency_key`.
 
-That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
-
-The backend wraps essential parts of the return creation process in its own step and stores the current step (known as recovery point) of the process with its associated Idempotency Key.
-
-Then, if the request is interrupted for any reason or an error occurs, the client can retry creating the return using the Idempotency Key, and the flow will continue from the last stored step.
+You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
 
 ### Return Creation Process Through the Customer
 

docs/content/modules/orders/swaps.md

@@ -39,16 +39,12 @@ In Medusa, Swaps are created by the customer through the storefront. This ensure
 
 ### Idempotency Key
 
-An Idempotency Key is a unique key associated with a swap. It is generated when the swap creation process is started. The idempotency key is stored in the `Swap` entity under the attribute `idempotency_key`.
-
-That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
-
-The backend wraps essential parts of the swap creation process in its own step and stores the current step (known as recovery point) of the process with its associated Idempotency Key.
-
-Then, if the request is interrupted for any reason or an error occurs, the client can retry creating the swap using the Idempotency Key, and the flow will continue from the last stored step.
+An Idempotency Key is a unique key associated with a swap. It is generated when the swap creation process is started and can be used to retry the swap creation safely if an error occurs. The idempotency key is stored in the `Swap` entity under the attribute `idempotency_key`.
 
 Keep in mind that the idempotency key stored in the swap is only used when creating the swap. All operations related to the swap’s cart and its completion use the [cart’s idempotency key](../carts-and-checkout/cart.md#idempotency-key).
 
+You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
+
 ### Swap Creation Process
 
 The customer starts by creating their swap, which can be done through the Create Swap endpoint. In this endpoint, the following steps are implemented: