Developer Documentation

Marketplace API Reference

Welcome to the official API documentation for our marketplace. This guide is specifically designed for mobile developers building our native Android application. All endpoints follow RESTful principles and return JSON responses.

Base API URL

https://ais-dev-cdqdzwi6przvqsmlvldogd-496623221749.asia-southeast1.run.app/api

All requests should use JSON headers.

Authentication

We use secure JWT-based authentication. Most protected resources require the Authorization header with a Bearer token.

POST/auth/login
Endpoint

Authenticate a user and return a JWT access token.

Request Body

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

Response Sample

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}
POST/auth/register
Endpoint

Create a new customer account.

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePassword123"
}

Response Sample

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 2,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Product Catalog

GET/products/home
Endpoint

Retrieve data for the mobile home screen, including featured banners, daily deals, and categorized collections.

Response Sample

{
  "hero": [
    {
      "id": 1,
      "title": "Summer Sale",
      "image": "..."
    }
  ],
  "deals": [
    {
      "id": 101,
      "title": "Smart Watch",
      "price": 2999,
      "sale_price": 1999
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "Electronics",
      "slug": "electronics"
    }
  ]
}
GET/products/[slug]
Endpoint

Get comprehensive details for a specific product including variants, offers, images, and technical specifications.

Response Sample

{
  "id": 112,
  "title": "Wireless Earbuds",
  "description": "High-quality audio...",
  "images": [
    "url1",
    "url2"
  ],
  "variants": [
    {
      "id": 1,
      "tsin": "WE001",
      "color": "Black"
    }
  ],
  "buyBox": {
    "price": 4999,
    "sale_price": 3999
  }
}

Cart & Checkout

GET/cart
Endpoint

Retrieve all items in the user's active shopping cart.

Required Headers

Authorization: Bearer <token>

Response Sample

{
  "items": [
    {
      "id": 5,
      "productId": 112,
      "quantity": 2,
      "price": 4999
    }
  ],
  "totalAmount": 9998
}
POST/cart
Endpoint

Add an item to the shopping cart.

Required Headers

Authorization: Bearer <token>

Request Body

{
  "productId": 112,
  "quantity": 1,
  "variantId": 1
}

Response Sample

{
  "success": true,
  "cartId": 44
}

Orders

GET/orders
Endpoint

Retrieve a list of all historical and active orders for the authenticated user.

Required Headers

Authorization: Bearer <token>

Response Sample

{
  "orders": [
    {
      "id": "ORD-12345",
      "status": "processing",
      "total": 12500,
      "createdAt": "2024-03-22T..."
    }
  ]
}
GET/order/[orderId]
Endpoint

Get full tracking details, items, and status updates for a specific order.

Required Headers

Authorization: Bearer <token>

Response Sample

{
  "id": "ORD-12345",
  "items": [
    {
      "title": "Wireless Earbuds",
      "quantity": 1,
      "price": 4999
    }
  ],
  "status": "shipped",
  "tracking": {
    "carrier": "Leopard",
    "number": "LEP99221"
  }
}

Need a custom endpoint?

Our backend team is ready to support your Android app requirements. Reach out for specialized mobile endpoints.