# Ecommerce API

- [Ecommerce API: Full-Featured REST API for E-Commerce](https://codebyahmed.mintlify.app/introduction.md): The Ecommerce API is a production-grade REST API for building e-commerce storefronts — covering auth, catalog, cart, checkout, orders, and reviews.
- [Authentication: Sessions and CSRF Tokens Explained](https://codebyahmed.mintlify.app/authentication.md): Learn how the Ecommerce API uses session cookies and CSRF tokens to authenticate requests, and how to log in, log out, and manage sessions.
- [Error Handling: Codes, Formats, and Recovery Steps](https://codebyahmed.mintlify.app/errors.md): Understand the Ecommerce API error envelope, HTTP status codes, and how to handle auth failures, validation errors, and rate limits in your app.
- [Pagination: Page and Limit Parameters for List Endpoints](https://codebyahmed.mintlify.app/concepts/pagination.md): All list endpoints in the Ecommerce API use cursor-free page-based pagination. Learn how to use the page and limit parameters and read the meta object.
- [Money Values: Decimal String Format and Parsing Guide](https://codebyahmed.mintlify.app/concepts/money-and-decimals.md): Monetary values in the Ecommerce API use a decimal string format to avoid floating-point errors. Learn the format rules and how to parse values.
- [Roles and Permissions: CUSTOMER, ADMIN, and SUPER_ADMIN](https://codebyahmed.mintlify.app/concepts/roles-and-permissions.md): The Ecommerce API has three user roles — CUSTOMER, ADMIN, and SUPER_ADMIN — each with different access to storefront and admin endpoints.
- [Create a New Customer Account via POST /auth/register](https://codebyahmed.mintlify.app/api-reference/auth/register.md): Create a new customer account with email, password, and phone number. Returns a session cookie and queues an email verification message.
- [Log In with Email and Password via POST /auth/login](https://codebyahmed.mintlify.app/api-reference/auth/login.md): Authenticate with email and password to receive a session cookie. Brute-force protection locks the account after 10 failed attempts for 15 minutes.
- [Log Out and Revoke the Current Session via Auth API](https://codebyahmed.mintlify.app/api-reference/auth/logout.md): Revoke the current session and clear the session cookie. Requires an active session; returns 204 even if the session was already revoked.
- [List and Revoke Your Account Sessions — Sessions API](https://codebyahmed.mintlify.app/api-reference/auth/sessions.md): List all active sessions for your account, revoke a specific session by its public ID, or sign out from every other device at once.
- [Email Verification — Verify and Resend Email Tokens](https://codebyahmed.mintlify.app/api-reference/auth/email-verification.md): Verify your registration email using the single-use token from your inbox, or request a new verification email if the original expired.
- [Reset Your Account Password Using Email OTP Verification](https://codebyahmed.mintlify.app/api-reference/auth/password-reset.md): Reset your account password in three steps: request a reset email, verify the 6-digit OTP code, then set a new password with the reset token.
- [User Profile — Get and Update Your Account Details](https://codebyahmed.mintlify.app/api-reference/users/profile.md): Retrieve your current profile or update your display name. Use PATCH /users/me to change first or last name; email and phone require separate flows.
- [Change Your Account Password with Session Revocation](https://codebyahmed.mintlify.app/api-reference/users/password.md): Change your password by providing your current password and a new one meeting complexity requirements. All other sessions are revoked on success.
- [Update Your Account Email Address with Verification](https://codebyahmed.mintlify.app/api-reference/users/email-change.md): Request an email change with your new address and current password. A verification link is sent to the new address; confirm it to complete the change.
- [Change Your Account Phone Number — OTP Verification](https://codebyahmed.mintlify.app/api-reference/users/phone-change.md): Update your phone number with an OTP verification. Submit your new E.164 phone number and current password, then confirm the 6-digit code sent via SMS.
- [Address Book — Manage Shipping and Billing Addresses](https://codebyahmed.mintlify.app/api-reference/users/addresses.md): Manage your saved addresses for shipping and billing. Create, update, set defaults, and delete addresses from your account address book.
- [Products API — Browse and Search the Product Catalog](https://codebyahmed.mintlify.app/api-reference/catalog/products.md): List and search customer-visible products, or fetch full product details including variants, pricing, and images. No authentication required.
- [Categories API — Browse and Filter Product Categories](https://codebyahmed.mintlify.app/api-reference/catalog/categories.md): List all product categories, fetch category details with product count, or list products within a specific category. No authentication required.
- [Cart API — Add Items, Update Quantities, and Check Out](https://codebyahmed.mintlify.app/api-reference/cart/cart.md): Manage your shopping cart — add product variants, update quantities, remove individual items, and clear the entire cart. Authentication required.
- [Orders API — Place Orders and Track Order History](https://codebyahmed.mintlify.app/api-reference/orders/orders.md): Place an order from your cart, browse your order history, and view full order details including item snapshots, payment status, and shipment info.
- [Reviews API — Read, Write, and Manage Product Reviews](https://codebyahmed.mintlify.app/api-reference/reviews/reviews.md): List approved reviews for any product, submit your own review after purchasing, and update or delete reviews you have written. No auth needed to read.
- [ImageKit Upload Auth — Get Signed Upload Credentials](https://codebyahmed.mintlify.app/api-reference/reviews/upload-auth.md): Get signed ImageKit authentication parameters for direct browser uploads. Use the returned token, signature, and endpoint to upload images for reviews.
- [Admin Products API — Create and Manage Products](https://codebyahmed.mintlify.app/api-reference/admin/products.md): Create, update, list, and soft-delete products in the catalog. Admin-only endpoint with support for search, brand filter, and deleted item visibility.
- [Admin Variants API — Manage Product Variants and SKUs](https://codebyahmed.mintlify.app/api-reference/admin/variants.md): Create and manage product variants with SKU, pricing, dimensions, discounts, and status. Each variant represents a purchasable unit of a product.
- [Admin Images API — Attach Product and Variant Images](https://codebyahmed.mintlify.app/api-reference/admin/images.md): Attach, reorder, and delete images for products and variants. Exactly one primary image is maintained per product. Upload images to ImageKit first, then register the URL here.
- [Admin Categories API — Manage Product Categories](https://codebyahmed.mintlify.app/api-reference/admin/categories.md): Create and manage product categories including active/inactive status, slug management, and product assignment. Requires ADMIN role.
- [Admin Inventory API — Manage Stock Levels and Reservations](https://codebyahmed.mintlify.app/api-reference/admin/inventory.md): View and adjust per-variant stock levels. The inventory system uses reservation semantics — stock can be reserved, committed, or released as orders progress.
- [Admin Orders API — Manage Orders and Status Transitions](https://codebyahmed.mintlify.app/api-reference/admin/orders.md): List all customer orders, view full order detail, and advance orders through the status lifecycle from pending to delivered, cancelled, or refunded.
- [Admin Coupons API — Create and Manage Discount Coupons](https://codebyahmed.mintlify.app/api-reference/admin/coupons.md): Create percentage or fixed-amount discount coupons, set usage limits and validity windows, and inspect redemption history per coupon.
- [Admin Users API — Search, Update, and Manage Accounts](https://codebyahmed.mintlify.app/api-reference/admin/users.md): List and manage customer accounts, update contact details, suspend or reactivate accounts, and change user roles. Requires ADMIN role.
- [Admin Reviews API — Approve and Reject Customer Reviews](https://codebyahmed.mintlify.app/api-reference/admin/reviews.md): View, approve, or reject customer reviews from the admin moderation queue. Rejected reviews are hidden from the public storefront.
- [Admin Accounts API — Manage Administrator Accounts](https://codebyahmed.mintlify.app/api-reference/admin/admins.md): Create, list, and manage admin accounts. Requires SUPER_ADMIN role. Use this endpoint to invite new administrators or revoke admin access.
- [Admin Analytics — Dashboard Statistics and P&L Reports](https://codebyahmed.mintlify.app/api-reference/admin/stats.md): Access dashboard statistics, revenue analytics, and P&L reports. Dashboard stats require ADMIN role; P&L and expense management require SUPER_ADMIN.
- [Admin Audit Log — Append-Only Record of Admin Actions](https://codebyahmed.mintlify.app/api-reference/admin/audit.md): Query the append-only audit log of all admin actions. Requires SUPER_ADMIN role. Each entry records the actor, action, target resource, and timestamp.