> For the complete documentation index, see [llms.txt](https://docs.enicebakerygh.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enicebakerygh.com/storefront-and-digital-commerce/api.md).

# REST API (v1) & Web Endpoints

This document provides the definitive technical specification for external and internal Application Programming Interfaces (APIs) provided by **Eniceberny Bakery and Culinary Hub**.

***

## 🌐 1. Architecture, Base URLs & Conventions

```mermaid
graph LR
    Client[Client App / Mobile / POS / Web] -->|HTTP REST JSON| Gateway[API Gateway / Laravel Router]
    Gateway --> Auth[Middleware / Rate Limiter]
    Auth --> Controllers[API v1 Controllers]
    Controllers --> Services[Domain Business Services]
    Services --> DB[(PostgreSQL / SQLite Database)]
```

### Base URLs

* **Production API**: `https://enicebakerygh.com/api/v1`
* **Documentation & MCP Relay**: `https://enicebakerygh.com/docs/~gitbook/mcp`
* **Local Development**: `http://localhost:8000/api/v1`

### Standard Request & Response Headers

All client applications communicating with the API must transmit the following HTTP headers:

| Header             | Expected Value      | Purpose                                  |
| ------------------ | ------------------- | ---------------------------------------- |
| `Content-Type`     | `application/json`  | Designates the payload formatting        |
| `Accept`           | `application/json`  | Enforces JSON response formatting        |
| `X-Requested-With` | `XMLHttpRequest`    | Flags Ajax request context               |
| `X-CSRF-TOKEN`     | `<meta csrf-token>` | Required for web-session based mutations |

### Standard Response Envelope

All API v1 endpoints return a uniform JSON envelope structure:

#### Success Response Envelope (HTTP 200 / 201)

```json
{
  "success": true,
  "message": "Human-readable confirmation message",
  "data": {},
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "total": 95
  }
}
```

#### Error Response Envelope (HTTP 400 / 404 / 422 / 500)

```json
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "customer_phone": [
      "Please enter a valid Ghanaian phone number (e.g. 024XXXXXXX or +233XXXXXXXXX)."
    ]
  }
}
```

***

## 📦 2. Catalog & Products API (`/api/v1/*`)

### 2.1 List Products

`GET /api/v1/products`

Retrieve a paginated collection of active, available delicacies and bakery items.

#### Query Parameters

| Parameter  | Type      | Required | Default | Description                                                               |
| ---------- | --------- | -------- | ------- | ------------------------------------------------------------------------- |
| `category` | `string`  | No       | `null`  | Filter by category slug (e.g. `continental-dishes`, `pastries-bakehouse`) |
| `search`   | `string`  | No       | `null`  | Keystroke search against item name or short description                   |
| `page`     | `integer` | No       | `1`     | Pagination page number                                                    |

#### Request Example (cURL)

```bash
curl -X GET "https://enicebakerygh.com/api/v1/products?category=pastries-bakehouse&search=meat" \
  -H "Accept: application/json"
```

#### Success Response (HTTP 200 OK)

```json
{
  "success": true,
  "data": [
    {
      "id": 4,
      "name": "Golden Flaky Beef Meat Pie",
      "slug": "golden-flaky-beef-meat-pie",
      "sku": "BAKE-PIE-001",
      "short_description": "Buttery shortcrust pastry filled with minced lean beef, vegetables, and savory spices.",
      "price": "18.00",
      "sale_price": null,
      "category": {
        "id": 3,
        "name": "Pastries & Bakehouse",
        "slug": "pastries-bakehouse"
      },
      "primary_image": {
        "id": 14,
        "image_path": "images/photo_4_2026-09-25_18-09-31.jpg",
        "alt_text": "Golden Flaky Beef Meat Pie"
      },
      "variants": [
        {
          "id": 8,
          "name": "Single Portion",
          "price": "18.00",
          "stock_quantity": 45
        },
        {
          "id": 9,
          "name": "Box of 6 (Party Pack)",
          "price": "100.00",
          "stock_quantity": 10
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 1,
    "total": 1
  }
}
```

***

### 2.2 Get Single Product Details

`GET /api/v1/products/{slug}`

Retrieve full product attributes, image galleries, portion variants, and customizable options.

#### Path Parameters

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `slug`    | `string` | Unique product slug (e.g. `signature-red-velvet-cake`) |

#### Request Example (cURL)

```bash
curl -X GET "https://enicebakerygh.com/api/v1/products/signature-red-velvet-cake" \
  -H "Accept: application/json"
```

#### Success Response (HTTP 200 OK)

```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Signature Red Velvet Celebration Cake",
    "slug": "signature-red-velvet-cake",
    "sku": "CK-RED-001",
    "description": "Layers of rich buttermilk sponge with Madagascar vanilla cream cheese frosting.",
    "price": "280.00",
    "category": {
      "id": 1,
      "name": "Celebration Cakes",
      "slug": "celebration-cakes"
    },
    "images": [
      {
        "id": 1,
        "image_path": "images/photo_7_2026-09-25_18-09-31.jpg",
        "is_primary": true
      }
    ],
    "variants": [
      { "id": 1, "name": "6-inch (Feeds 6-8)", "price": "280.00", "stock_quantity": 12 },
      { "id": 2, "name": "8-inch (Feeds 12-16)", "price": "400.00", "stock_quantity": 8 },
      { "id": 3, "name": "10-inch (Feeds 20+)", "price": "580.00", "stock_quantity": 4 }
    ],
    "options": [
      {
        "id": 1,
        "name": "Cake Inscription",
        "type": "text",
        "is_required": false
      },
      {
        "id": 2,
        "name": "Frosting Style",
        "type": "select",
        "is_required": true,
        "values": [
          { "id": 1, "name": "Smooth Modern Finish", "price_modifier": "0.00" },
          { "id": 2, "name": "Textured Rosettes (+GH₵ 30)", "price_modifier": "30.00" }
        ]
      }
    ]
  }
}
```

***

### 2.3 List Categories

`GET /api/v1/categories`

Retrieve all active culinary categories with product count metadata.

#### Request Example (cURL)

```bash
curl -X GET "https://enicebakerygh.com/api/v1/categories" \
  -H "Accept: application/json"
```

#### Success Response (HTTP 200 OK)

```json
{
  "success": true,
  "data": [
    { "id": 1, "name": "Pastries & Bakehouse", "slug": "pastries-bakehouse", "products_count": 8 },
    { "id": 2, "name": "Continental Dishes", "slug": "continental-dishes", "products_count": 6 },
    { "id": 3, "name": "Authentic Ghanaian Cuisine", "slug": "ghanaian-cuisine", "products_count": 7 },
    { "id": 4, "name": "Celebration Cakes", "slug": "celebration-cakes", "products_count": 5 },
    { "id": 5, "name": "Fresh Drinks & Juices", "slug": "fresh-drinks-juices", "products_count": 4 }
  ]
}
```

***

## 🛒 3. Commerce & Checkout API (`/api/v1/*`)

### 3.1 Place Storefront Order

`POST /api/v1/checkout`

Atomically validates cart items, customer details, calculates delivery fees, creates the order, and initializes payment.

#### Request Headers

* `Content-Type: application/json`
* `Accept: application/json`

#### Request Payload Body (`CheckoutRequest`)

```json
{
  "customer_name": "Kwame Mensah",
  "customer_phone": "0244123456",
  "customer_email": "kwame.mensah@example.com",
  "order_type": "delivery",
  "delivery_address": "Plot 14 Block B, Ahodwo",
  "delivery_city": "Kumasi",
  "gps_address": "AK-039-2311",
  "landmark": "Near Shell Petrol Station",
  "payment_method": "momo",
  "special_instructions": "Extra shito pepper sauce please",
  "items": [
    {
      "product_id": 4,
      "quantity": 2,
      "variant_id": 8,
      "notes": "Serve hot"
    }
  ]
}
```

#### Success Response (HTTP 201 Created)

```json
{
  "success": true,
  "message": "Order created successfully.",
  "order": {
    "id": 89,
    "order_number": "EB-20260927-1845",
    "customer_name": "Kwame Mensah",
    "customer_phone": "0244123456",
    "subtotal": "36.00",
    "delivery_fee": "15.00",
    "discount_amount": "0.00",
    "total": "51.00",
    "status": "pending",
    "payment_status": "pending",
    "payment_method": "momo",
    "order_type": "delivery",
    "items": [
      {
        "id": 142,
        "product_name": "Golden Flaky Beef Meat Pie",
        "quantity": 2,
        "unit_price": "18.00",
        "subtotal": "36.00"
      }
    ]
  },
  "payment": {
    "gateway": "momo",
    "reference": "EB-PAY-68DE1049",
    "redirect_url": "https://checkout.paystack.com/3f08b3e9x8",
    "instructions": "Authorize the prompt sent to your mobile phone."
  }
}
```

***

### 3.2 Get Order Details by Order Number

`GET /api/v1/orders/{orderNumber}`

Look up complete order state, items, live delivery tracking history, and financial receipts.

#### Path Parameters

| Parameter     | Type     | Description                                       |
| ------------- | -------- | ------------------------------------------------- |
| `orderNumber` | `string` | Unique order identifier (e.g. `EB-20260927-1845`) |

#### Request Example (cURL)

```bash
curl -X GET "https://enicebakerygh.com/api/v1/orders/EB-20260927-1845" \
  -H "Accept: application/json"
```

#### Success Response (HTTP 200 OK)

```json
{
  "success": true,
  "data": {
    "id": 89,
    "order_number": "EB-20260927-1845",
    "status": "preparing",
    "payment_status": "paid",
    "subtotal": "36.00",
    "delivery_fee": "15.00",
    "total": "51.00",
    "items": [
      {
        "product_name": "Golden Flaky Beef Meat Pie",
        "quantity": 2,
        "unit_price": "18.00",
        "subtotal": "36.00"
      }
    ],
    "status_histories": [
      {
        "status": "pending",
        "notes": "Order placed by customer",
        "created_at": "2026-09-27T18:45:10Z"
      },
      {
        "status": "confirmed",
        "notes": "Payment received via MoMo",
        "created_at": "2026-09-27T18:46:02Z"
      },
      {
        "status": "preparing",
        "notes": "In bakehouse oven",
        "created_at": "2026-09-27T18:48:30Z"
      }
    ],
    "transactions": [
      {
        "transaction_reference": "EB-PAY-68DE1049",
        "gateway": "momo",
        "amount": "51.00",
        "currency": "GHS",
        "status": "success",
        "paid_at": "2026-09-27T18:46:02Z"
      }
    ]
  }
}
```

***

## ⚡ 4. Reactive Web & Interactive Cart Endpoints

These endpoints power the Alpine.js sliding shopping cart drawer and instant client interactions.

### 4.1 Live Cart Drawer Data

`GET /cart/drawer-data`

Fetches real-time shopping cart count and rendered subtotal.

#### Response (HTTP 200 OK)

```json
{
  "items_count": 3,
  "subtotal": "GH₵ 72.00",
  "items": [
    {
      "id": 104,
      "product_id": 4,
      "name": "Golden Flaky Beef Meat Pie",
      "quantity": 2,
      "unit_price": "GH₵ 18.00",
      "line_total": "GH₵ 36.00",
      "image": "/images/photo_4_2026-09-25_18-09-31.jpg"
    }
  ]
}
```

### 4.2 Add Item to Basket

`POST /cart/add`

* **Payload**:

  ```json
  {
    "product_id": 4,
    "quantity": 1,
    "variant_id": 8,
    "options": {
      "inscription": "Congratulations!"
    }
  }
  ```
* **Response**: `{ "success": true, "message": "Added to cart", "cart_count": 4 }`

### 4.3 Update Item Quantity

`POST /cart/update/{itemId}`

* **Payload**: `{ "quantity": 3 }`
* **Response**: `{ "success": true, "subtotal": "GH₵ 108.00" }`

### 4.4 Remove Item from Basket

`DELETE /cart/remove/{itemId}`

* **Response**: `{ "success": true, "message": "Item removed" }`

### 4.5 Apply Promotional Coupon

`POST /cart/apply-coupon`

* **Payload**: `{ "code": "ENICEWELCOME10" }`
* **Response**: `{ "success": true, "discount_amount": "GH₵ 10.00", "new_total": "GH₵ 98.00" }`

***

## 🖥️ 5. Point of Sale (POS) Terminal Endpoints

### 5.1 Process Counter POS Sale

`POST /admin/pos/checkout`

* **Payload**:

  ```json
  {
    "customer_name": "Walk-in Guest",
    "customer_phone": "0532342126",
    "payment_method": "cash",
    "order_type": "takeaway",
    "discount_amount": 0.00,
    "items": [
      { "id": 4, "name": "Golden Flaky Beef Meat Pie", "quantity": 2, "price": 18.00 }
    ]
  }
  ```
* **Response (HTTP 200 OK)**:

  ```json
  {
    "success": true,
    "order_id": 142,
    "order_number": "EB-20260927-9912",
    "receipt_url": "/orders/EB-20260927-9912/receipt"
  }
  ```

***

## 🔐 6. Payment Webhook Protocols

### 6.1 Paystack Webhook Receiver

`POST /webhooks/paystack`

Receives asynchronous server-to-server transaction notifications.

#### Security & Authentication

* Header: `X-Paystack-Signature`
* The payload HMAC SHA512 hash must match the signature computed with `PAYSTACK_SECRET_KEY`.

#### Webhook Payload Structure

```json
{
  "event": "charge.success",
  "data": {
    "reference": "EB-PAY-68DE1049",
    "amount": 5100,
    "currency": "GHS",
    "status": "success",
    "gateway_response": "Approved",
    "paid_at": "2026-09-27T18:46:02.000Z",
    "channel": "mobile_money",
    "metadata": {
      "order_number": "EB-20260927-1845"
    }
  }
}
```

***

## 🤖 7. Model Context Protocol (MCP) Relay

### 7.1 GitBook MCP Assistant Endpoint

`POST /docs/~gitbook/mcp`

Relays automated Model Context Protocol requests from the embedded GitBook AI assistant directly to `https://docs.enicebakerygh.com/~gitbook/mcp`.

* **Headers**: `Content-Type: application/json`
* **Supported Methods**: `POST`, `OPTIONS`
* **Authentication**: Origin-verified cross-site request relay.

***

*For database entities or payment configurations, consult the* [*Database Schema Guide*](/architecture-and-engineering/database.md) *and* [*Payment Systems Guide*](/storefront-and-digital-commerce/payments.md)*.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enicebakerygh.com/storefront-and-digital-commerce/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.