Storefront Guides
My Account
Storefront Guides
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 RequiredAll 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
Managing User Profile
These endpoints allow users to view and update their basic information.
- Retrieve User Details:
GET /auth/user/{id}: Fetches the completeUserobject, 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 likefirst_name,last_name,email, orphone. (Note: Changing email/phone might trigger a verification flow usingPOST /auth/generate-otpwithotp_action: update-emailorupdate-phone, followed byPOST /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 mainGET /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
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 includesis_default_billingandis_default_shippingflags.- 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 theCustomerAddressfields plus optionalis_default_billingandis_default_shippingflags.
- 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
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 byorder_datedescending).status[]: Filter orders by specific statuses (e.g.,shipped,delivered,cancelled).
- Response: Contains
orders(array ofOrderListobjects, a summary view) andpagination. 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 (OrderDetailobject) 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 ofOrderShipmentobjects).
- 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 ofOrderPaymentobjects).
- Retrieve Order Refunds:
GET /orders/{order_number}/refunds: Lists any refunds processed for the order.- Response: Contains
refunds(array ofOrderRefundobjects).
- Cancel Order:
POST /orders/{order_number}/cancel: Allows a customer to request cancellation of an entire order.- Availability: Check the
is_cancellation_allowedflag returned byGET /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_modeorbank_transfer).bank_account_id: Required ifrefund_modeisbank_transfer. (Requires separate flow for securely collecting and verifying bank details, potentially using Admin APIs or dedicated UI).feedback: Optional additional comments.
- Response:
200 OKwith the updatedOrderDetailshowing status as ‘cancelled’.
- Retry Payment:
POST /orders/{order_number}/retry-payment: Initiates a new payment attempt for an order where the initial payment failed butis_retry_availablewas true (checked viaGET /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:
CreateOrderReturnschema, containingreturn_items(array detailingproduct_id,sku,quantity,resolution- refund/replacement,return_reason) and potentiallyshipping_addressfor pickup. - Response:
200 OKwith theOrderReturnobject 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
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 ofLoyaltyPointActivityobjects) and pagination.
Review Management
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 ofCustomerReviewobjects representing reviews already submitted by the user (across all products).ready_for_review: An array ofCustomerReadyForReviewobjects, listing products from completed orders that the user hasn’t reviewed yet.
- Use
reviewsto show a “My Reviews” history. - Use
ready_for_reviewto prompt users to submit new reviews, linking them to the product page or a dedicated review submission form (POST /catalog/products/{product_id}/reviews).