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.

Authentication

Learn how session cookies and CSRF tokens work together to secure every request you make to the API.

Error Handling

Understand the unified error envelope, HTTP status codes, and how to handle failures gracefully in your application.

Storefront API

Explore customer-facing endpoints for registration, catalog browsing, cart management, checkout, and order tracking.

Admin API

Manage products, inventory, orders, coupons, users, and analytics through the full suite of admin endpoints.

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.

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

   curl -c cookies.txt -X POST https://api.example.com/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email": "[e-mail]", "password": "S3cure!Pass"}'
   
2. 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.

   curl -b cookies.txt https://api.example.com/api/v1/auth/csrf-token
   
3. 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.

   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}'
   
4. 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.

   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"
     }'
   

The live API is hosted at 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.