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.
Managing User Profile
These endpoints allow users to view and update their basic information.
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.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
).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).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.POST /auth/change-password
: Allows logged-in users to change their existing password.Address Book
Manage the customerβs saved billing and shipping 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.GET /customers/{user_id}/addresses/{address_id}
: Fetches the details of one specific 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.PUT /customers/{user_id}/addresses/{address_id}
: Modifies an existing address. Allows changing details and default status flags.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:
Address Management Flow
Order History & Management
Allow customers to view their past orders and perform post-purchase actions.
GET /orders
: Retrieves a paginated list of the customerβs orders.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
).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).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.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.shipments
(array of OrderShipment
objects).GET /orders/{order_number}/payments
: Lists all payment transactions (successful payments, potentially failed attempts if logged) associated with the order.payments
(array of OrderPayment
objects).GET /orders/{order_number}/refunds
: Lists any refunds processed for the order.refunds
(array of OrderRefund
objects).POST /orders/{order_number}/cancel
: Allows a customer to request cancellation of an entire order.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.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.200 OK
with the updated OrderDetail
showing status as βcancelledβ.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.POST /orders/{order_number}/return
: Allows customers to initiate a return request for specific items within an order.CreateOrderReturn
schema, containing return_items
(array detailing product_id
, sku
, quantity
, resolution
- refund/replacement, return_reason
) and potentially shipping_address
for pickup.200 OK
with the OrderReturn
object details. Return requests typically require approval via the Admin Portal.GET /orders/{order_number}/return/{return_id}
: Fetches details of a specific return request.GET /orders/returns
(less common for storefront): List all return requests initiated by the user across orders.Order History / Cancellation Flow:
Order History / Cancellation Flow
Loyalty Program Activity
If the loyalty program is enabled, users can track their points.
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.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).loyalty_points_activity
(array of LoyaltyPointActivity
objects) and pagination.Review Management
Allow users to see reviews theyβve submitted and potentially items awaiting 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.reviews
to show a βMy Reviewsβ history.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
).