Punguzo API Documentation

The Punguzo API gives developers everything they need to start selling on Africa’s leading mobile money platforms using Punguzo.
Use our RESTful endpoints to list products, manage inventory,process orders and manage payments — all within a secure, scalable environment designed for easy integration and rapid go-to-market.

Base URL: http://punguzo.com

Authentication

Most Punguzo API endpoints require authentication to ensure secure access. After a successful login, the API returns a session_token, which must be included in the headers of all subsequent requests.

How to Authenticate:

Send the session token in the Authorization header with a Bearer scheme.

Authorization: Bearer [your_session_token]

API Endpoints

POST /user/api/users/login

Authenticates a user with their email and password, returning a session token and user profile.

Request Body

Parameter Type Required Description
email string Yes The user's email address.
password string Yes The user's password.

Example Request

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

Responses

200 OK Login successful 
{
  "message": "Login successful",
  "session_token": "eyJ0eXAiOiJK...",
  "profile": {
    "user_id": 1,
    "username": "johndoe",
    "email": "user@example.com",
    "merchant_id": 10,
    "first_name": "John",
    "last_name": "Doe",
    "roles": ["merchant", "admin"]
  }
}
400 Bad Request Missing email or password.
401 Unauthorized Invalid credentials.
GET /merchant/dashboard/{merchant_id}

Retrieves key performance indicators (KPIs) and top-selling products for a specific merchant.

Parameters

Path Parameters
merchant_id integer Yes The unique identifier for the merchant.
Query Parameters
start_date string No Start of the date range in YYYYMMDD format. Defaults to the start of the current week.
end_date string No End of the date range in YYYYMMDD format. Defaults to the end of the current week.

Example Request

GET /merchant/dashboard/1?start_date=20250601&end_date=20250630

Response

200 OK 
{
  "total_sales": 15905000.0,
  "total_products_sold": 470,
  "total_product_views": 19350,
  "top_sellers": [
    {
      "id": 1,
      "name": "Magic Juicer Multifunction Blender Heavy Duty",
      "selling_price": 49000,
      "discount_percentage": 30,
      "image": "https://example.com/image1.png",
      "sold": 5308
    }
  ]
}
GET /product/api/get_all_products

Retrieves a paginated list of products. Supports extensive filtering, sorting, and searching.

Query Parameters

Parameter Type Description
min_price float Filters products by a minimum discounted price.
max_price float Filters products by a maximum discounted price.
limit integer Specifies the number of products to return per page (default: 10000).
offset integer Specifies the number of products to skip for pagination (default: 0).
sort_by string Determines the sorting order. Accepted values are: Recommended, Price, Recent, Discount.
categories string A comma-separated list of category names to filter products by.
search_keyword string Searches for a keyword across product names, categories, and shop names.
POST /product/api/product

Creates a new product entry in the system with the provided details.

Request Body

Field Type Required Description
name string Yes The name of the product.
description string Yes A detailed description of the product.
original_price float Yes The original price of the product. Must be ≥ 0.
discount_price float Yes The discounted price. Must be ≥ 0 and ≤ original_price.
merchant_id integer Yes The ID of the merchant who owns the product.
category_id integer Yes The ID of the product's category.

Responses

201 Created Product created successfully. 
{
  "success": true,
  "message": "New product created successfully.",
  "product_id": 123
}
400 Bad Request Validation errors. 
{
  "success": false,
  "message": "Validation errors occurred.",
  "errors": [
    "Product name cannot be empty.",
    "Discount price cannot be greater than original price."
  ]
}
GET /product/api/categories

Fetches a comprehensive list of all parent categories and their subcategories.

Response

200 OK 
[
  {
    "id": 1,
    "name": "Electronics",
    "description": "Devices and gadgets",
    "image_url": "https://example.com/images/electronics.jpg",
    "subcategories": [
      {
        "id": 11,
        "name": "Smartphones",
        "description": "Mobile phones and accessories",
        "image_url": "https://example.com/images/smartphones.jpg",
        "archived": false
      }
    ]
  }
]
POST /media/api/product_images

Uploads one or more images for a product using a multipart form-data request.

Request

The request must use the multipart/form-data content type.

Field Type Required Description
file file Yes The image file to be uploaded.

Response

200 OK Image uploaded successfully. 
{
  "message": "Image uploaded successfully",
  "image_url": "https://punguzo.com/media/product_images/123.jpg"
}