Skip to main content
The public API endpoints require no authentication — you can call them directly from a browser, a mobile app, or any backend service without an API token. Use them to build customer-facing product search, shop discovery pages, nearby-store finders, and receipt viewers.
Shops are only returned by public endpoints if they are approved and active in the Mutasib platform. Individual products must have is_public set to true to appear in public search results and shop product listings.

​
Search Products

Search across all public products on the platform with optional filters for category, price range, and shop. GET /api/v1/public/search/
​
string
Search query string. Matches against product names, descriptions, and barcodes.
​
string
Filter results to a specific product category (e.g. grocery, dairy, beverages).
​
number
Minimum unit price filter.
​
number
Maximum unit price filter.
​
integer
Restrict results to a single shop.
Returns an array of ProductListOut objects matching the search criteria, sorted by relevance.

​
List Public Shops

Browse all approved, active shops on the platform. Optionally filter by category. GET /api/v1/public/shops/
​
string
Filter shops by their primary business category (e.g. grocery, pharmacy, bakery).
Returns an array of ShopListOut objects.

​
Get Shop Details

Retrieve the public profile of a single shop by its ID, including name, location, and category. GET /api/v1/public/shops/{shop_id}/
Returns a ShopOut object with the full public profile of the shop.

​
Get Shop Products

List all public products offered by a specific shop. Supports search and category filtering. GET /api/v1/public/shops/{shop_id}/products/
​
string
Filter products by name or barcode.
​
integer
Filter products by category ID.
Returns an array of ProductListOut objects belonging to that shop where is_public is true.

​
Nearby Shops

Find approved shops within a given radius of a geographic coordinate. Results are sorted by distance from the provided location. GET /api/v1/public/shops/nearby/
​
number
required
Latitude of the search origin (decimal degrees, e.g. 36.7).
​
number
required
Longitude of the search origin (decimal degrees, e.g. 3.05).
​
number
Search radius in kilometres. Defaults to 10.
Example response
Returns an array of ShopListOut objects, each augmented with a distance_km field indicating how far the shop is from the provided coordinates.

​
Receipt by Token

Retrieve the full details of a sale using its receipt_token. This endpoint is public — no authentication is needed — making it suitable for QR code links you print on paper receipts or send via SMS. GET /api/v1/public/receipt/{token}
Returns a SaleOut object with the full list of purchased items. See Sales API for SaleOut field definitions.

​
Receipt PDF

Download a formatted PDF copy of a receipt. Useful for customers who need a printable or saveable version. GET /api/v1/public/receipt/{token}/pdf
Returns a binary PDF file with Content-Type: application/pdf. The PDF includes the shop name, cashier, itemized list, and total amount.