Authentication: 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.

  • 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.

​
Address Book

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:

​
Order History & Management

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.
  • Initiate Order Return:
    • POST /orders/{order_number}/return: Allows customers to initiate a return request for specific items within an order.
    • Request Body: CreateOrderReturn schema, containing return_items (array detailing product_id, sku, quantity, resolution - refund/replacement, return_reason) and potentially shipping_address for pickup.
    • Response: 200 OK with the OrderReturn object details. Return requests typically require approval via the Admin Portal.
  • Retrieve Return Details:
    • 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:

​
Loyalty Program Activity

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.

​
Review Management

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).