> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# My Account
> This section details the APIs used to build the "My Account" area of your storefront, allowing logged-in customers to manage their profile, view past orders, handle returns or cancellations, update addresses, track loyalty points, and manage their reviews.
**Authentication Required**
All endpoints described in this section require a **logged-in user's Bearer token** for authentication. The `{user_id}` path parameter in many Customer-related endpoints must correspond to the user associated with the token.
These endpoints allow users to view and update their basic information.
* **Retrieve User Details:**
* `GET /auth/user/{id}`: Fetches the complete `User` object, including name, email, phone, verification status, profile image URL, and notification preferences. Use the user's ID obtained after login.
* Display this information on the profile page.
* **Update User Details:**
* `PUT /auth/user/{id}`: Allows users to update fields like `first_name`, `last_name`, `email`, or `phone`. (Note: Changing email/phone might trigger a verification flow using `POST /auth/generate-otp` with `otp_action: update-email` or `update-phone`, followed by `POST /auth/verify-otp`).
* **Manage Profile Image:**
* `POST /auth/user/{id}/profile-image`: Upload a new profile picture (`multipart/form-data`).
* `PUT /auth/user/{id}/profile-image`: Replace the existing profile picture.
* `DELETE /auth/user/{id}/profile-image`: Remove the profile picture.
* `GET /auth/user/{id}/profile-image`: Retrieve the current image URL (often included in the main `GET /auth/user/{id}` response anyway).
* **Manage Notification Preferences:**
* `GET /auth/user/{id}/notification-preferences`: Retrieve current opt-in/out status for transactional, promotional, and newsletter communications across channels (email, SMS, WhatsApp).
* `PUT /auth/user/{id}/notification-preferences`: Update these preferences based on user selections.
* **Password Management (If applicable):**
* `POST /auth/change-password`: Allows logged-in users to change their existing password.
Manage the customer's saved billing and shipping addresses.
* **List Addresses:**
* `GET /customers/{user_id}/addresses`: Retrieves a paginated list of all saved addresses for the user. Each address object includes `is_default_billing` and `is_default_shipping` flags.
* Use this to display the address book.
* **Retrieve Single Address:**
* `GET /customers/{user_id}/addresses/{address_id}`: Fetches the details of one specific address.
* **Create Address:**
* `POST /customers/{user_id}/addresses`: Adds a new address to the user's address book. The request body includes the `CustomerAddress` fields plus optional `is_default_billing` and `is_default_shipping` flags.
* **Update Address:**
* `PUT /customers/{user_id}/addresses/{address_id}`: Modifies an existing address. Allows changing details and default status flags.
* **Delete Address:**
* `DELETE /customers/{user_id}/addresses/{address_id}`: Removes an address from the address book. Ensure checks are in place if the address is linked to active subscriptions.
**Address Management Flow:**
Allow customers to view their past orders and perform post-purchase actions.
* **List Orders:**
* `GET /orders`: Retrieves a paginated list of the customer's orders.
* **Query Parameters:**
* `user_id`: **Required**. The ID of the logged-in customer.
* `page`, `limit`, `sort_by`: Standard pagination/sorting (e.g., sort by `order_date` descending).
* `status[]`: Filter orders by specific statuses (e.g., `shipped`, `delivered`, `cancelled`).
* **Response:** Contains `orders` (array of `OrderList` objects, a summary view) and `pagination`. Display key info like order number, date, status, total amount, and primary item image(s).
* **Retrieve Order Detail:**
* `GET /orders/{order_number}`: Fetches the complete details (`OrderDetail` object) for a single order, including all items, addresses, pricing breakdown, payment info, cancellation status, etc. Use this for the detailed order view page.
* **Retrieve Order Shipments:**
* `GET /orders/{order_number}/shipments`: Retrieves shipment details associated with an order (tracking number, status, courier, items included in each shipment). An order might have multiple shipments.
* **Response:** Contains `shipments` (array of `OrderShipment` objects).
* **Retrieve Order Payments:**
* `GET /orders/{order_number}/payments`: Lists all payment transactions (successful payments, potentially failed attempts if logged) associated with the order.
* **Response:** Contains `payments` (array of `OrderPayment` objects).
* **Retrieve Order Refunds:**
* `GET /orders/{order_number}/refunds`: Lists any refunds processed for the order.
* **Response:** Contains `refunds` (array of `OrderRefund` objects).
* **Cancel Order:**
* `POST /orders/{order_number}/cancel`: Allows a customer to request cancellation of an entire order.
* **Availability:** Check the `is_cancellation_allowed` flag returned by `GET /orders/{order_number}` before showing the cancel button. Cancellation might only be possible before the order is processed or shipped.
* **Request Body:**
* `cancellation_reason`: Required reason text.
* `refund_mode`: Required (`original_payment_mode` or `bank_transfer`).
* `bank_account_id`: Required if `refund_mode` is `bank_transfer`. (Requires separate flow for securely collecting and verifying bank details, potentially using Admin APIs or dedicated UI).
* `feedback`: Optional additional comments.
* **Response:** `200 OK` with the updated `OrderDetail` showing status as 'cancelled'.
* **Retry Payment:**
* `POST /orders/{order_number}/retry-payment`: Initiates a new payment attempt for an order where the initial payment failed but `is_retry_available` was true (checked via `GET /orders/{order_number}/payment-status`). See Checkout Flow (Step 9/10) for usage.
* **Returns:**
* Returns are currently **managed by store administrators** through the Admin Portal. There is no storefront API for customers to initiate returns directly.
* Customers who need to return items should contact the store's customer support, and the admin will process the return from the Admin Portal.
* Return APIs for the storefront are under development.
**Order History / Cancellation Flow:**
If the loyalty program is enabled, users can track their points.
* **Retrieve Loyalty Summary:**
* `GET /customers/{user_id}/loyalty`: Fetches the user's current loyalty status, including tier, total earned, redeemed, balance, and redeemable points. Display this in a dedicated loyalty section or user dashboard.
* **List Loyalty Activity:**
* `GET /customers/{user_id}/loyalty-points-activity`: Retrieves a paginated list of all transactions where points were earned or redeemed (e.g., points earned from an order, points redeemed in a cart).
* **Response:** Contains `loyalty_points_activity` (array of `LoyaltyPointActivity` objects) and pagination.
Allow users to see reviews they've submitted and potentially items awaiting review.
* **List User Reviews & Items Ready for Review:**
* `GET /customers/{user_id}/reviews`: Fetches two lists:
* `reviews`: An array of `CustomerReview` objects representing reviews already submitted by the user (across all products).
* `ready_for_review`: An array of `CustomerReadyForReview` objects, listing products from completed orders that the user hasn't reviewed yet.
* Use `reviews` to show a "My Reviews" history.
* Use `ready_for_review` to prompt users to submit new reviews, linking them to the product page or a dedicated review submission form (`POST /catalog/products/{product_id}/reviews`).