Getting Started
Storefront APIs
Configure your store
Storefront APIs
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 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.
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:
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 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:
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 ofLoyaltyPointActivityobjects) 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 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).
Previous
SubscriptionsThe Subscriptions module allows you to offer products and services on a recurring basis, enabling business models like "Subscribe & Save," SaaS, content access, and custom refill schedules. Commerce Engine provides APIs to define subscription plans on products, let users initiate subscriptions, and manage the lifecycle of those subscriptions.
Next
Assistant
Responses are generated using AI and may contain mistakes.