NearbyMe - Food Delivery Marketplace

Overview

Complete REST API documentation for the NearbyMe food delivery marketplace platform.

This documentation covers all REST API endpoints for the NearbyMe food delivery platform. Use the navigation on the left to browse by category or scroll through all endpoints.

Authentication

## Authentication NearbyMe uses Supabase Auth for authentication. All authenticated endpoints require a valid JWT token in the Authorization header. ### Getting Started 1. **Sign Up**: Create an account at `/auth/sign-up` 2. **Sign In**: Authenticate at `/auth/login` 3. **Get Session**: After authentication, Supabase provides a session with access token ### Using Authentication in API Calls For all authenticated endpoints, include the Authorization header: ``` Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Note**: When testing via browser (same origin), the session cookie is automatically sent. For Postman or external testing, you need to include the token manually. ### Roles - **customer**: Can browse restaurants, manage cart, place orders - **vendor**: Can manage restaurant, menu, view/process orders - **rider**: Can view available deliveries, update delivery status - **admin**: Full system access

Test Data Reference

Use these pre-seeded values for testing:

Test Kitchen Lagos

a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d

End-to-End User Flows

Complete workflows for each user role from onboarding to core actions

Customer Flow: Browse, Order, Track

1Sign Up

Create a customer account

Navigate to /auth/sign-up and select "Customer" role

2Browse Restaurants

View available restaurants

GET /api/restaurants

curl -X GET "/api/restaurants?latitude=6.5244&longitude=3.3792"

3View Menu

Get menu items for a restaurant

GET /api/restaurants/{id}/menu-items

curl -X GET "/api/restaurants/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/menu-items"

4Add to Cart

Add items to shopping cart

POST /api/cart

curl -X POST "/api/cart" -H "Authorization: Bearer TOKEN" -d '{"menu_item_id": "aaaa1111-1111-1111-1111-111111111111", "quantity": 2}'

5Apply Promo (Optional)

Apply a discount code

POST /api/cart/promo

curl -X POST "/api/cart/promo" -H "Authorization: Bearer TOKEN" -d '{"promo_code": "WELCOME20"}'

6Checkout

Create order from cart

POST /api/orders

curl -X POST "/api/orders" -H "Authorization: Bearer TOKEN" -d '{"delivery_address": "45 Admiralty Way, Lagos", "delivery_latitude": 6.4355, "delivery_longitude": 3.4500}'

7Track Order

Monitor order status

GET /api/orders/{id}

curl -X GET "/api/orders/ORDER_ID" -H "Authorization: Bearer TOKEN"

Order Status Transitions

Valid order status transitions by role:

From Status	To Status	Allowed Roles
placed	accepted	vendor
placed	cancelled	customervendoradmin
accepted	preparing	vendor
accepted	cancelled	vendoradmin
preparing	ready	vendor
ready	picked_up	rider
picked_up	delivered	rider

Error Responses

Standard error response format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

401Unauthorized- Missing or invalid authentication

403Forbidden- Insufficient permissions for this action

404Not Found- Resource does not exist

400Bad Request- Invalid request body or parameters

409Conflict- Resource conflict (e.g., duplicate entry)

422Unprocessable- Validation error in request data

500Server Error- Internal server error

Restaurants

Manage restaurants and their settings

GET/api/restaurants

List all restaurants

POST/api/restaurants

vendor

Create a restaurant

GET/api/restaurants/{id}

Get restaurant details

PATCH/api/restaurants/{id}

vendor

Update restaurant

PATCH/api/restaurants/{id}/status

vendor

Toggle restaurant open/closed

Cart

Shopping cart management

GET/api/cart

customer

Get current cart

POST/api/cart

customer

Add item to cart

DELETE/api/cart

customer

Clear cart

PATCH/api/cart/items/{id}

customer

Update cart item

DELETE/api/cart/items/{id}

customer

Remove cart item

POST/api/cart/promo

customer

Apply promo code

DELETE/api/cart/promo

customer

Remove promo code

Orders

Order management and tracking

GET/api/orders

customervendorrideradmin

List orders

POST/api/orders

customer

Create order from cart

GET/api/orders/{id}

customervendorrideradmin

Get order details

PATCH/api/orders/{id}/status

vendorrideradmin

Update order status

POST/api/orders/{id}/assign-rider

vendoradmin

Assign rider to order

Riders

Rider management and tracking

GET/api/riders

vendoradmin

List available riders

POST/api/riders

rider

Create rider profile

GET/api/riders/me

rider

Get my rider profile

PATCH/api/riders/me

rider

Update my rider profile

PATCH/api/riders/me/status

rider

Update availability status

POST/api/riders/me/location

rider

Update current location

GET/api/riders/me/earnings

rider

Get my earnings

Payments

Payment processing and earnings

POST/api/payments

customer

Create payment

POST/api/payments/{id}/confirm

customeradmin

Confirm payment

GET/api/vendor/earnings

vendor

Get vendor earnings