API Reference

Build with Byfluence. This reference covers core resources, authentication, and common patterns.

Base URL

process.env.NEXT_PUBLIC_API_URL

Configure NEXT_PUBLIC_API_URL in .env.local.

Authentication

Use Bearer tokens in the Authorization header. Obtain tokens via login or OAuth.

Login

POST /v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "strong-password"
}

Authenticated request (cURL)

curl -X GET   "$NEXT_PUBLIC_API_URL/v1/auth/me"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Shops

Create and manage shops.

Create shop

POST /v1/shops
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "My Shop",
  "slug": "my-shop",
  "country": "ET",
  "category": "fashion"
}

Get shop

GET /v1/shops/{shopId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Wallet

Check balances, top up, and transfer.

Get wallet

GET /v1/wallet
Authorization: Bearer YOUR_ACCESS_TOKEN

Transfer

POST /v1/wallet/transfers
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "toUserId": "uuid",
  "amount": 5000,
  "currency": "ETB"
}

Physical Products

Create, update, and list products with inventory.

Create product

POST /v1/products
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "title": "T-Shirt",
  "price": 1999,
  "currency": "ETB",
  "sku": "TS-RED-M",
  "inventory": 100
}

Get product

GET /v1/products/{productId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Responses

Standard envelope for success responses.

{
  "data": { /* resource */ },
  "message": "Operation successful",
  "success": true
}

Errors

Errors return an HTTP status and message.

{
  "message": "Invalid credentials",
  "success": false,
  "errors": [
    { "path": "email", "code": "invalid", "message": "Email not found" }
  ]
}

Pagination

Use query params page and limit.

GET /v1/products?page=1&limit=20