Quickstart Guide This guide walks you through making your first API calls to the E-Commerce API. You’ll learn how to register a user, authenticate, browse products, manage a shopping cart, and create orders.
Base URL All API requests should be made to:
Authentication Most endpoints require authentication using a JWT token. After logging in, include the token in the Authorization header:
Authorization: Bearer YOUR_JWT_TOKEN
Register a New User
Create a new customer account by sending a POST request to /auth/register. curl -X POST http://localhost:3000/auth/register \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "email": "[email protected] ", "password": "securepassword123" }'
Response: { "message" : "Usuario registrado exitosamente" , "user" : { "id" : "1" , "name" : "John Doe" , "email" : "[email protected] " , "role" : "customer" , "createdAt" : "2026-03-06T10:30:00.000Z" } }
Passwords must be at least 6 characters long. The password is hashed and never returned in API responses.
Login to Get Access Token
Authenticate with your credentials to receive a JWT token for subsequent requests. curl -X POST http://localhost:3000/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepassword123" }'
Response: { "token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "user" : { "id" : "1" , "name" : "John Doe" , "email" : "[email protected] " , "role" : "customer" } }
Store the JWT token securely. You’ll need it for all authenticated requests. The token should be included in the Authorization header as Bearer YOUR_TOKEN.
Browse Available Products
Retrieve the list of available products. This endpoint is public and doesn’t require authentication. curl http://localhost:3000/products
Response: [ { "id" : 1 , "name" : "Wireless Headphones" , "description" : "Premium noise-cancelling headphones with 30-hour battery life" , "price" : 199.99 , "stock" : 50 , "imageUrl" : "http://localhost:3000/uploads/headphones.jpg" , "categoryId" : 1 , "createdAt" : "2026-03-01T10:00:00.000Z" }, { "id" : 2 , "name" : "Smart Watch" , "description" : "Fitness tracking smartwatch with heart rate monitor" , "price" : 299.99 , "stock" : 30 , "imageUrl" : "http://localhost:3000/uploads/smartwatch.jpg" , "categoryId" : 1 , "createdAt" : "2026-03-02T14:30:00.000Z" } ]
You can also fetch a specific product by ID: curl http://localhost:3000/products/1
Add Products to Cart
Add items to your shopping cart. This endpoint requires authentication. curl -X POST http://localhost:3000/cart/add \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ "productId": 1, "quantity": 2 }'
Response: { "id" : 1 , "userId" : 1 , "productId" : 1 , "quantity" : 2 , "createdAt" : "2026-03-06T11:00:00.000Z" }
The quantity must be at least 1. If you add the same product again, the quantities will be combined.
View Your Cart
Retrieve all items in your shopping cart with product details and calculated totals. curl http://localhost:3000/cart \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: { "items" : [ { "id" : 1 , "productId" : 1 , "quantity" : 2 , "product" : { "id" : 1 , "name" : "Wireless Headphones" , "price" : 199.99 , "imageUrl" : "http://localhost:3000/uploads/headphones.jpg" }, "subtotal" : 399.98 } ], "total" : 399.98 }
Update cart item quantity: curl -X PUT http://localhost:3000/cart/item/1 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{"quantity": 3}'
Remove item from cart: curl -X DELETE http://localhost:3000/cart/item/1 \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Create an Order
Convert your cart items into an order. This will clear your cart and create a permanent order record. curl -X POST http://localhost:3000/orders \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: { "id" : 1 , "userId" : 1 , "total" : 399.98 , "status" : "pending" , "createdAt" : "2026-03-06T11:15:00.000Z" , "items" : [ { "id" : 1 , "orderId" : 1 , "productId" : 1 , "quantity" : 2 , "price" : 199.99 , "product" : { "id" : 1 , "name" : "Wireless Headphones" , "imageUrl" : "http://localhost:3000/uploads/headphones.jpg" } } ] }
Creating an order will clear your cart. Make sure your cart contains all desired items before creating an order.
View Order History
Retrieve all your past orders or fetch a specific order by ID. # Get all orders curl http://localhost:3000/orders \ -H "Authorization: Bearer YOUR_JWT_TOKEN" # Get specific order curl http://localhost:3000/orders/1 \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response (all orders): [ { "id" : 1 , "userId" : 1 , "total" : 399.98 , "status" : "pending" , "createdAt" : "2026-03-06T11:15:00.000Z" , "items" : [ { "id" : 1 , "orderId" : 1 , "productId" : 1 , "quantity" : 2 , "price" : 199.99 } ] } ]
Admin Operations Admin users have additional privileges to manage products and categories. To perform admin operations, you must first create an admin user.
Create Admin User Only existing admins can create new users with specific roles:
curl -X POST http://localhost:3000/auth/create-user \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ADMIN_JWT_TOKEN" \ -d '{ "name": "Admin User", "email": "[email protected] ", "password": "securepassword123", "role": "admin" }'
Create a Product Admin users can create new products with image uploads using multipart/form-data:
curl -X POST http://localhost:3000/products \ -H "Authorization: Bearer ADMIN_JWT_TOKEN" \ -F "name=Wireless Mouse" \ -F "description=Ergonomic wireless mouse with precision tracking" \ -F "price=49.99" \ -F "stock=100" \ -F "categoryId=1" \ -F "image=@/path/to/mouse.jpg"
Response: { "id" : 3 , "name" : "Wireless Mouse" , "description" : "Ergonomic wireless mouse with precision tracking" , "price" : 49.99 , "stock" : 100 , "imageUrl" : "http://localhost:3000/uploads/wireless-mouse-1234567890.jpg" , "categoryId" : 1 , "createdAt" : "2026-03-06T12:00:00.000Z" }
Product images are required and must be less than 5MB. Supported formats include JPEG, PNG, and WebP.
Update a Product curl -X PUT http://localhost:3000/products/3 \ -H "Authorization: Bearer ADMIN_JWT_TOKEN" \ -F "price=44.99" \ -F "stock=150"
Delete a Product curl -X DELETE http://localhost:3000/products/3 \ -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Next Steps
API Reference Explore all available endpoints and their detailed documentation
Authentication Learn more about JWT authentication and security best practices
Error Handling Understand error codes and how to handle API errors
Rate Limiting Learn about API rate limits and best practices
Common Issues
This error occurs when your JWT token is missing, invalid, or expired. Make sure you’re including the token in the Authorization header as Bearer YOUR_TOKEN. You may need to login again to get a fresh token.
Authentication endpoints (/auth/register and /auth/login) are rate limited to 10 requests per 15 minutes. If you exceed this limit, wait 15 minutes before trying again.
Product Image Upload Fails
Ensure your image is less than 5MB and in a supported format (JPEG, PNG, WebP). The image field must be named image in the multipart form data.
Cannot Create Order from Empty Cart
You must have at least one item in your cart before creating an order. Add products to your cart using /cart/add first.