> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ecommerce API: Full-Featured REST API for E-Commerce

> The Ecommerce API is a production-grade REST API for building e-commerce storefronts — covering auth, catalog, cart, checkout, orders, and reviews.

The Ecommerce API is a production-grade REST API that gives you everything you need to build a fully functional e-commerce platform. Built on session-cookie authentication with CSRF protection, it exposes a clean set of endpoints for customer-facing storefronts and admin dashboards alike. All money values are decimal strings, timestamps are ISO 8601 UTC, and every resource is identified by a prefixed public ID — keeping your integration predictable and safe.

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/authentication">
    Learn how session cookies and CSRF tokens work together to secure every request you make to the API.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/errors">
    Understand the unified error envelope, HTTP status codes, and how to handle failures gracefully in your application.
  </Card>

  <Card title="Storefront API" icon="cart-shopping" href="/api-reference/auth/register">
    Explore customer-facing endpoints for registration, catalog browsing, cart management, checkout, and order tracking.
  </Card>

  <Card title="Admin API" icon="shield-halved" href="/api-reference/admin/products">
    Manage products, inventory, orders, coupons, users, and analytics through the full suite of admin endpoints.
  </Card>
</CardGroup>

## What You Can Build

The Ecommerce API is designed to power every layer of a modern online store. With it you can build:

* **Storefront shopping experiences** — browse categories, search products, manage a cart, apply coupons, and place orders with a full checkout flow
* **Customer account management** — register, verify email, reset passwords, manage addresses, and track order history
* **Product catalog browsing** — list products with filtering and pagination, view detailed product pages with variants and images
* **Order tracking** — retrieve order status, line items, shipping details, and timeline updates in real time
* **Review system** — submit and retrieve product reviews with ratings, subject to admin moderation before they surface publicly
* **Admin dashboard** — manage the full product catalog, process orders through status transitions, moderate reviews, issue coupons, and view sales analytics

## Getting Started

Follow these four steps to go from zero to a placed order with the Ecommerce API.

<Steps>
  <Step title="Register or log in to get a session cookie">
    Call `POST /auth/register` to create a new customer account, or `POST /auth/login` with an existing email and password. Either endpoint sets a `session` HttpOnly cookie on success — you must carry this cookie on every subsequent authenticated request.

    ```bash theme={null}
    curl -c cookies.txt -X POST https://api.example.com/api/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{"email": "jane@example.com", "password": "S3cure!Pass"}'
    ```
  </Step>

  <Step title="Fetch a CSRF token for write operations">
    Before any state-changing request (POST, PATCH, or DELETE), call `GET /auth/csrf-token` using your active session. Pass the returned token in the `x-csrf-token` header on your write request.

    ```bash theme={null}
    curl -b cookies.txt https://api.example.com/api/v1/auth/csrf-token
    ```
  </Step>

  <Step title="Browse the catalog and add items to your cart">
    Product and category listing endpoints are public — no authentication required. Once you have a session, add items to your cart with `POST /cart/items`, specifying the product variant and quantity.

    ```bash theme={null}
    curl -b cookies.txt -X POST https://api.example.com/api/v1/cart/items \
      -H "Content-Type: application/json" \
      -H "x-csrf-token: csrf_abc123" \
      -d '{"variant_public_id": "var_01H", "quantity": 2}'
    ```
  </Step>

  <Step title="Place an order">
    Call `POST /orders` with your shipping address public ID, payment method (`"mock"`), and an optional coupon code. The API validates stock, calculates totals, and creates your order — returning a full order object with line items, pricing, and status.

    ```bash theme={null}
    curl -b cookies.txt -X POST https://api.example.com/api/v1/orders \
      -H "Content-Type: application/json" \
      -H "x-csrf-token: csrf_abc123" \
      -d '{
        "address_public_id": "adr_01H",
        "payment_method": "mock"
      }'
    ```
  </Step>
</Steps>

<Note>
  The live API is hosted at **[https://ecommerce-api-l3a4.onrender.com](https://ecommerce-api-l3a4.onrender.com)**. Use this base URL when testing against the deployed environment. All examples in these docs use `https://api.example.com/api/v1` as the production base URL — substitute accordingly.
</Note>