📱 Customer App API Documentation v1

Getting Started

Base URL

Development:

http://localhost:8000/api

Production:

https://api.gaga.ma/api

Authentication

Most endpoints require a valid Bearer token. Include these headers in every request:

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json

Example:

Authorization: Bearer 1|xxxxxxxxxxxxxxxx

Home

Fetches all layout blocks required to render the mobile app home screen dynamically.

Included Blocks

Example Response Snippet

{
  "success": true,
  "data": {
    "main_categories": [...],
    "categories": [...],
    "offers": [...],
    "featured_products": [...],
    "trending_products": [...],
    "top_rated_stores": [...],
    "popular_near_you": [...]
  }
}

Search

Global search for products and stores.

Query Parameters

Example Response

{
  "success": true,
  "data": {
    "stores": [
      { "id": 1, "name": "The Burger Joint", "logo": "..." }
    ],
    "products": [
      { "id": 22, "name": "Classic Burger", "price": 10.99, "store_id": 1 }
    ]
  }
}

Stores Nearby

Fetches stores within delivery radius, supporting extensive filtering.

Query Parameters

Store Catalog

Fetches full menu, products, and categories for a specific store.

Response Blocks

Checkout (Create Order)

Processes the cart and creates a new order in the database.

Body Parameters (JSON)

Item Object Structure

Example Request

{
  "store_id": 1,
  "address_id": 3,
  "code_promo": "SUMMER10",
  "items": [
    {
      "product_id": 22,
      "quantity": 2,
      "options": [1, 5],
      "supplements": [3]
    }
  ]
}

Example Response

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order_id": 100,
    "status": "pending_acceptance",
    "total": 45.90
  }
}

Customer Orders (List)

Fetches the user's order history. This payload is lightweight and omits deep customization details.

Response Payload Example

{
  "success": true,
  "data": [
    {
      "id": 100,
      "status": "delivered",
      "subtotal": 13.38,
      "total": 15.38,
      "created_at": "2026-06-24T14:15:00.000000Z",
      "store": {
        "id": 1,
        "name": "The Burger Joint",
        "logo": "url"
      },
      "items": [
        {
          "product_id": 22,
          "product_name": "Classic Burger",
          "quantity": 1,
          "base_price": 13.38,
          "total_price": 13.38
        }
      ]
    }
  ]
}

Order Details & Tracking

Fetches the full heavy payload for a single order, powering the Details and Live Tracking screens.

Order Journey

Included Heavy Details

• store: Complete store object.
• driver: Dispatched driver details including real-time latitude and longitude.
• user_address: Exact delivery coordinates and address lines.
• items: Includes nested options and supplements matrices.
• timeline: Dynamic array built from actual server timestamps for the tracking UI stepper.

Tracking Example Response

{
  "success": true,
  "data": {
    "id": 100,
    "status": "preparing",
    "total": 86.76,
    "store": { ... },
    "user_address": { ... },
    "driver": {
      "id": 5,
      "name": "John Courier",
      "phone": "+212600000000",
      "latitude": 33.5890,
      "longitude": -7.6031
    },
    "timeline": [
      {
        "status": "pending_acceptance",
        "at": "2026-06-24T14:10:00.000000Z"
      },
      {
        "status": "preparing",
        "at": "2026-06-24T14:15:00.000000Z"
      }
    ],
    "items": [
      {
        "product_id": 22,
        "product_name": "Delicious Burger",
        "quantity": 2,
        "base_price": 13.38,
        "total_price": 86.76,
        "options": [
          { "id": 1, "name": "Large", "price": 20 }
        ],
        "supplements": [
          { "id": 1, "name": "Extra Cheese", "price": 10 }
        ]
      }
    ]
  }
}

Payments

Endpoints related to processing payments for customer orders.

Fetches all active, supported payment methods.

Initiates payment processing for a specific order_id using a specific payment_method_id.

Common Error Responses

401 Unauthorized

Returned when the Bearer token is missing, expired, or invalid.

{
  "message": "Unauthenticated."
}

422 Unprocessable Entity

Returned when validation fails (e.g. missing required fields like store_id or quantity).

{
  "errors": {
    "store_id": ["The store id field is required."],
    "items.0.quantity": ["The items.0.quantity field must be at least 1."]
  }
}

404 Not Found

Returned when querying for an entity that doesn't exist.

{
  "message": "No query results for model [App\\Models\\Order] 9999"
}

500 Server Error

Internal server error. Will contain detailed exception traces in local environment, but masked in production.

{
  "message": "Server Error"
}

Quick Testing

Use these cURL commands to quickly test the APIs. Don't forget to replace {token} with your Bearer Token.

1. Homepage

curl -X GET "http://localhost:8000/api/v1/homepage" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

2. Search

curl -X GET "http://localhost:8000/api/v1/global/search?q=burger" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

3. Nearby Stores

curl -X GET "http://localhost:8000/api/v1/stores/nearby?lat=33.5&lng=-7.5&radius=10" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

4. Store Catalog

curl -X GET "http://localhost:8000/api/v1/store/stores/1/catalog" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

5. Checkout

curl -X POST "http://localhost:8000/api/v1/customer/orders" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{"store_id":1, "address_id":3, "items":[{"product_id":22, "quantity":2}]}'

6. Orders (List)

curl -X GET "http://localhost:8000/api/v1/customer/orders" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

7. Order Tracking (Show)

curl -X GET "http://localhost:8000/api/v1/customer/orders/100" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

Customer App Backend Readiness

• Homepage APIs ✅
• Search APIs ✅
• Store Catalog APIs ✅
• Checkout APIs ✅
• Orders APIs ✅
• Tracking APIs ✅
• Payment APIs ✅