A production-ready REST API for e-commerce platforms built with Laravel 13, featuring JWT authentication, shopping cart management, order processing, Stripe payment integration, and interactive Swagger UI documentation.
- Features
- Tech Stack
- Architecture
- Quick Start
- Quick Start with Docker
- API Documentation
- API Endpoints
- Payment Flow
- Product Filtering
- Running Tests
- Environment Variables
- Project Structure
- JWT Authentication — register, login, logout with token-based auth
- Product Catalog — categories, products with filtering by category, price, and search
- Shopping Cart — add, update, remove items with real-time stock validation
- Order Management — create orders from cart with automatic tax calculation (10%)
- Stripe Integration — Payment Intent creation and webhook handling
- Stock Management — automatic stock decrement on order creation
- Webhook Security — Stripe signature verification for all webhook events
- Swagger UI — interactive API documentation at
/api/documentation - 24 Automated Tests — full test coverage for auth, products, cart, and orders
- Docker Support — ready to run with Docker Compose
| Layer | Technology |
|---|---|
| Language | PHP 8.4 |
| Framework | Laravel 13 |
| Database | MySQL 8.0 |
| Authentication | JWT (tymon/jwt-auth) |
| Payments | Stripe PHP SDK |
| API Docs | L5-Swagger (OpenAPI 3.0) |
| Testing | PHPUnit 12 |
| Container | Docker & Docker Compose |
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ Client App │────▶│ Laravel API │────▶│ MySQL DB │
│ (Mobile/React) │ │ │ └─────────────┘
└─────────────────┘ │ JWT Auth │
│ REST API │ ┌─────────────┐
┌─────────────────┐ │ Webhooks │────▶│ Stripe │
│ Stripe Events │────▶│ Swagger UI │ │ Payments │
└─────────────────┘ └──────────────┘ └─────────────┘
- PHP 8.2+
- Composer 2.x
- MySQL 8.0
- Stripe account (for payments)
# Clone the repository
git clone https://github.com/pavelsilinskiiwork/ecommerce-api.git
cd ecommerce-api
# Install dependencies
composer install
# Copy environment file
cp .env.example .env
# Generate application key
php artisan key:generate
# Generate JWT secret
php artisan jwt:secret
# Configure database in .env
DB_HOST=127.0.0.1
DB_DATABASE=ecommerce
DB_USERNAME=root
DB_PASSWORD=
# Run migrations and seed sample data
php artisan migrate --seed
# Start the server
php artisan serveAPI available at: http://localhost:8000/api/v1
Swagger UI available at: http://localhost:8000/api/documentation
git clone https://github.com/pavelsilinskiiwork/ecommerce-api.git
cd ecommerce-api
cp .env.example .env
# Start all services
docker-compose up -d
# Run setup commands
docker-compose exec app php artisan key:generate
docker-compose exec app php artisan jwt:secret
docker-compose exec app php artisan migrate --seedServices:
- API:
http://localhost:8000 - Swagger UI:
http://localhost:8000/api/documentation - phpMyAdmin:
http://localhost:8080
Interactive Swagger UI is available at:
http://localhost:8000/api/documentation
The documentation includes:
- All endpoints with request/response examples
- JWT Bearer authentication support — click Authorize and enter your token
- Try it out feature — test endpoints directly from the browser
- Full request body schemas with validation rules
How to use Swagger UI:
- Register or login via
/api/v1/registeror/api/v1/login - Copy the token from the response
- Click Authorize button (top right)
- Enter:
Bearer your_token_here - Now you can test all protected endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/register |
No | Register new user |
| POST | /api/v1/login |
No | Login and get JWT token |
| POST | /api/v1/logout |
Yes | Logout current user |
| GET | /api/v1/me |
Yes | Get current user info |
Register request:
{
"name": "Pavel Silinskii",
"email": "pavel@example.com",
"password": "password123",
"password_confirmation": "password123"
}Login response:
{
"token": "eyJ0eXAiOiJKV1Qi...",
"token_type": "bearer",
"expires_in": 3600
}| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/categories |
No | List all active categories |
| GET | /api/v1/categories/{id} |
No | Get category with products |
| POST | /api/v1/admin/categories |
Yes | Create category |
| PUT | /api/v1/admin/categories/{id} |
Yes | Update category |
| DELETE | /api/v1/admin/categories/{id} |
Yes | Delete category |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/products |
No | List products with filters |
| GET | /api/v1/products/{id} |
No | Get single product |
| POST | /api/v1/admin/products |
Yes | Create product |
| PUT | /api/v1/admin/products/{id} |
Yes | Update product |
| DELETE | /api/v1/admin/products/{id} |
Yes | Delete product |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/cart |
Yes | View cart with totals |
| POST | /api/v1/cart/add |
Yes | Add product to cart |
| PUT | /api/v1/cart/items/{id} |
Yes | Update item quantity |
| DELETE | /api/v1/cart/items/{id} |
Yes | Remove item from cart |
| DELETE | /api/v1/cart |
Yes | Clear entire cart |
Add to cart request:
{
"product_id": 1,
"quantity": 2
}Cart response:
{
"cart": {
"id": 1,
"items": [
{
"product_id": 1,
"quantity": 2,
"price": "999.99",
"product": { "name": "iPhone 15 Pro" }
}
]
},
"total": 1999.98,
"items_count": 2
}| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/orders |
Yes | List user's orders |
| POST | /api/v1/orders |
Yes | Create order from cart |
| GET | /api/v1/orders/{id} |
Yes | Get order details |
| POST | /api/v1/orders/{id}/payment |
Yes | Create Stripe Payment Intent |
Create order request:
{
"shipping_address": {
"name": "Pavel Silinskii",
"street": "123 Main St",
"city": "Needham",
"state": "MA",
"zip": "02492",
"country": "US"
},
"notes": "Please leave at door"
}Order response:
{
"id": 1,
"order_number": "ORD-6A84D35A4436E",
"status": "pending",
"subtotal": "1999.98",
"tax": "200.00",
"total": "2199.98",
"currency": "USD",
"items": [...]
}| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/orders/{id}/payment |
Yes | Create Stripe Payment Intent |
Payment Intent response:
{
"client_secret": "pi_xxx_secret_xxx",
"payment_intent_id": "pi_xxx",
"amount": 2199.98,
"currency": "USD"
}| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/webhook/stripe |
Stripe Sig | Handle Stripe events |
Supported webhook events:
payment_intent.succeeded→ order status set topaidpayment_intent.payment_failed→ order status set tocancelled
1. Add products to cart
POST /api/v1/cart/add
2. Create order from cart
POST /api/v1/orders
→ Order created with status: "pending"
→ Cart is cleared
→ Stock is reduced
3. Create Payment Intent
POST /api/v1/orders/{id}/payment
→ Returns: client_secret, payment_intent_id
4. Frontend confirms payment
stripe.confirmPayment({ client_secret })
5. Stripe sends webhook
POST /api/webhook/stripe
→ payment_intent.succeeded
→ Order status updated to "paid"
# Filter by category
GET /api/v1/products?category_id=1
# Search by name
GET /api/v1/products?search=iphone
# Filter by price range
GET /api/v1/products?min_price=100&max_price=1000
# Combine filters
GET /api/v1/products?category_id=1&max_price=500&search=pro| Status | Description |
|---|---|
pending |
Order created, awaiting payment |
paid |
Payment confirmed via Stripe webhook |
processing |
Order being prepared |
shipped |
Order shipped to customer |
delivered |
Order delivered |
cancelled |
Order cancelled or payment failed |
refunded |
Order refunded |
# Run all tests
php artisan test
# Run specific test suite
php artisan test --filter=CartTest
php artisan test --filter=OrderTest
php artisan test --filter=ProductTest
php artisan test --filter=AuthTest
# Run with coverage
php artisan test --coverageTest coverage:
| Suite | Tests | Status |
|---|---|---|
| AuthTest | 4 | ✅ Pass |
| ProductTest | 5 | ✅ Pass |
| CartTest | 6 | ✅ Pass |
| OrderTest | 7 | ✅ Pass |
| ExampleTest | 2 | ✅ Pass |
| Total | 24 | ✅ All pass |
# Application
APP_NAME="E-Commerce API"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ecommerce
DB_USERNAME=root
DB_PASSWORD=
# JWT
JWT_SECRET=your-jwt-secret
# Stripe
STRIPE_KEY=pk_test_your_publishable_key
STRIPE_SECRET=sk_test_your_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
# Swagger
L5_SWAGGER_GENERATE_ALWAYS=trueecommerce-api/
├── app/
│ ├── Http/
│ │ ├── Controllers/Api/
│ │ │ ├── AuthController.php
│ │ │ ├── CategoryController.php
│ │ │ ├── ProductController.php
│ │ │ ├── CartController.php
│ │ │ ├── OrderController.php
│ │ │ ├── PaymentController.php
│ │ │ ├── WebhookController.php
│ │ │ └── SwaggerController.php
│ │ └── Requests/
│ ├── Models/
│ │ ├── User.php
│ │ ├── Category.php
│ │ ├── Product.php
│ │ ├── Cart.php
│ │ ├── CartItem.php
│ │ ├── Order.php
│ │ ├── OrderItem.php
│ │ └── Payment.php
├── database/
│ ├── migrations/
│ └── seeders/
│ ├── CategorySeeder.php
│ └── ProductSeeder.php
├── routes/
│ └── api.php
├── tests/
│ └── Feature/
│ ├── AuthTest.php
│ ├── ProductTest.php
│ ├── CartTest.php
│ └── OrderTest.php
├── docker-compose.yml
├── Dockerfile
├── .dockerignore
└── README.md
After running php artisan db:seed, the database will contain:
Categories: Electronics, Clothing, Books, Home & Garden
Products:
- iPhone 15 Pro — $999.99
- Samsung Galaxy S24 — $899.99
- MacBook Pro 14" — $1,999.99
- Nike Air Max — $129.99
- Clean Code (book) — $39.99
- Laravel Up & Running (book) — $49.99
Built by Pavel Silinskii — Full-Stack PHP Developer with 15+ years of experience building e-commerce platforms, ERP integrations, and payment gateway solutions.
- GitHub: github.com/pavelsilinskiiwork
- LinkedIn: linkedin.com/in/pavel-silinskii
- Contra: contra.com/pavel-silinskii
- LeetCode: leetcode.com/u/Hc1hqfu6wJ — 119 problems solved
MIT License — feel free to use this project as a reference or starting point.