How to Implement Claim Order Flow in Storefront
In this document, you’ll learn how to implement the claim order flow in a storefront to allow customers to claim their orders.
This flow was added starting from Medusa v1.7. You can learn more about upgrading in the upgrade guide.
When a guest customer places an order, their order is not associated with any customer. The order is only associated with an email that the guest customer provides during checkout.
This email must be an email that isn’t used with an existing account. It can, however, be used to create another order as a guest customer.
After this customer registers with a different email and logs in, they can claim their order by providing the order’s ID. An email will then be sent to the email address associated with the order.
The email should contain a link to a page in the storefront, and the link should have a token as a parameter. This token will be used for verification.
The customer must then click the link in the email they received. If the token is valid, the order will be associated with the customer.
What You’ll Learn
In this document, you’ll learn how to implement two parts of this flow:
- Allow customers to claim their orders.
- Verify a claim to an order.
It's assumed that you already have a Medusa backend installed and set up. If not, you can follow the quickstart guide to get started.
It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.
This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
Handle Order Claim Request Event
When the customer requests to claim the order, an event will be triggered. You should subscribe to this event to send a confirmation email to the customer when the event is triggered.
You can learn how to implement this flow in this documentation.
In addition, it is assumed you already have a logged-in customer before performing the steps in this document. You can refer to the API reference for more details on that.
Request to Claim an Order
When the customer wants to claim an order, they must supply its ID.
To allow the customer to claim an order, send a request to the Claim an Order endpoint:
- Medusa JS Client
- Fetch API
This request accepts as a body parameter the array
order_ids. Each item in the array is the ID of an order that the customer wants to claim. You can pass more than one ID.
If the customer’s request has been processed successfully, the request returns a response with a
200 status code.
The customer at this point will receive an email with a link to verify their claim on the order.
Manually Verify a Claim to an Order
The link in the email that the customer receives should be a page in your storefront that accepts a
token query parameter.
Then, you send a request to the Verify Claim Order endpoint:
- Medusa JS Client
- Medusa React
- Fetch API
This request accepts as a body parameter the string
token. This would be the token passed as a parameter to your storefront page through the link in the email.
If the verification is successful, the order will now be associated with the customer and the customer will be able to see it among their orders.