PB
Positive Bazar API v1.0 REST
Frontend Web & Mobile App Reference
SPECIFICATION

API Architecture & Integration Standards

The Positive Bazar API is structured according to RESTful principles, using versioned endpoints under /api/v1/. All endpoints return standardized JSON payloads and leverage Laravel Sanctum Bearer tokens for secure authenticated access across web frontend and native iOS/Android mobile applications.

Accept Header
application/json
Guarantees JSON responses on errors/redirects
Content-Type
application/json
Use multipart/form-data for file uploads
Authorization
Bearer <token>
Required for protected endpoints
MOBILE NATIVE & FLUTTER

Mobile Application Integration Guidelines

Essential implementation practices for Flutter, React Native, Swift (iOS), and Kotlin (Android) developers:

1. Authentication & Token Lifecycle

Store the returned token in secure encrypted hardware storage (e.g., FlutterSecureStorage or iOS Keychain / Android KeyStore). Attach as Authorization: Bearer <token> on every protected request.

2. Handling 401 Unauthorized

Implement a global HTTP Interceptor. When receiving status code 401, wipe the stored token from secure storage and navigate the user to the Login screen with a notification.

3. Media & Image URL Formatting

The API returns relative image paths (e.g. uploads/products/image.jpg) or absolute URLs. Ensure your image helper prepends the backend base asset domain if the string does not start with http.

4. Infinite Scroll Pagination

Paginated lists return an envelope with pagination.current_page and pagination.last_page. Only trigger the next page request when current_page < last_page.

Standard Response Envelopes

Every endpoint outputs consistent structure using the unified helper:

200 OK / 201 Created 
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": { ... },
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95
  }
}
422 Unprocessable Entity 
{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "phone": ["The phone number field is required."],
    "password": ["The password must be at least 6 characters."]
  }
}
LIVE TESTER

Interactive API Console

Execute real API requests directly from this browser page
Idle
// Hit "Send Request" to test endpoint live...

Authentication & Account Management 9 endpoints

Phone OTP, registration, passwordless OTP, password reset, and email auth flows.

POST /auth/check-phone Public API

Check Phone Registration Status

Checks if phone number exists and whether customer has already set a password.

Request Parameters
Parameter Type Required Description
phone string Yes 11-digit Bangladesh phone number (e.g. 01712345678)
Example Request Body 
{
  "phone": "01712345678"
}
200 OK Response 
{
  "status": "success",
  "message": "Account found",
  "data": {
    "exists": true,
    "has_password": true,
    "name": "Tanvir Ahmed"
  }
}
POST /auth/registration-otp Public API

Send Phone Registration OTP

Generates and delivers 4/6-digit verification OTP to the customer mobile number.

Request Parameters
Parameter Type Required Description
phone string Yes 11-digit mobile number
Example Request Body 
{
  "phone": "01712345678"
}
200 OK Response 
{
  "status": "success",
  "message": "OTP sent successfully",
  "data": {
    "expires_in": 300
  }
}
POST /auth/verify-otp Public API

Verify Phone OTP

Verifies the OTP submitted by the user. If valid, permits account registration or password reset.

Request Parameters
Parameter Type Required Description
phone string Yes 11-digit phone number
otp string Yes Verification OTP code
Example Request Body 
{
  "phone": "01712345678",
  "otp": "1234"
}
200 OK Response 
{
  "status": "success",
  "message": "OTP verified successfully",
  "data": {
    "verified": true
  }
}
POST /auth/register Public API

Customer Registration (Phone OTP)

Completes registration and creates Sanctum authentication token.

Request Parameters
Parameter Type Required Description
name string Yes Full Name
phone string Yes 11-digit phone
otp string Yes Verified OTP
password string Yes Minimum 6 characters
ref string Optional Affiliate referral code (optional)
Example Request Body 
{
  "name": "Tanvir Ahmed",
  "phone": "01712345678",
  "otp": "1234",
  "password": "secretPassword"
}
200 OK Response 
{
  "status": "success",
  "message": "Registration successful",
  "data": {
    "token": "1|abcdef123456789...",
    "customer": {
      "id": 45,
      "name": "Tanvir Ahmed",
      "phone": "01712345678"
    }
  }
}
POST /auth/login Public API

Customer Login

Authenticates customer credentials and returns Sanctum Bearer token.

Request Parameters
Parameter Type Required Description
phone string Yes 11-digit phone
password string Yes Account password
Example Request Body 
{
  "phone": "01712345678",
  "password": "secretPassword"
}
200 OK Response 
{
  "status": "success",
  "message": "Login successful",
  "data": {
    "token": "2|987654321fedcba...",
    "customer": {
      "id": 45,
      "name": "Tanvir Ahmed",
      "phone": "01712345678"
    }
  }
}
POST /auth/forgot-password Public API

Forgot Password OTP

Sends password reset OTP to verified registered account.

Request Parameters
Parameter Type Required Description
phone string Yes 11-digit phone number
Example Request Body 
{
  "phone": "01712345678"
}
200 OK Response 
{
  "status": "success",
  "message": "Reset OTP sent successfully"
}
POST /auth/reset-password Public API

Reset Password

Resets password after verifying OTP code.

Request Parameters
Parameter Type Required Description
phone string Yes Phone number
otp string Yes OTP code
password string Yes New password
Example Request Body 
{
  "phone": "01712345678",
  "otp": "1234",
  "password": "brandNewPassword"
}
200 OK Response 
{
  "status": "success",
  "message": "Password updated successfully"
}
GET /auth/me Bearer Token Required

Get Authenticated User Profile

Fetches the current logged in customer account details and affiliate metadata.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "id": 45,
    "name": "Tanvir Ahmed",
    "phone": "01712345678",
    "email": "user@example.com",
    "is_affiliate": true,
    "is_wholesaler": false
  }
}
POST /auth/logout Bearer Token Required

Customer Logout

Revokes the current Sanctum access token.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "message": "Logged out successfully"
}

Storefront, Products & Catalog 7 endpoints

Home page sliders, categories, subcategories, product listing, search, filtering, combo bundles, and product reviews.

GET /home-page Public API

Get Full Home Page Data

Returns main banners, flash sales, featured categories, trending items, and section blocks.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "sliders": [
      {
        "id": 1,
        "title": "Summer Sale",
        "image_url": "uploads/sliders/1.jpg",
        "link": "/products"
      }
    ],
    "featured_categories": [
      {
        "id": 4,
        "name": "Grocery",
        "slug": "grocery",
        "icon": "uploads/cat/grocery.png"
      }
    ],
    "flash_deals": [],
    "new_arrivals": []
  }
}
GET /categories Public API

List All Categories

Returns tree structure of active categories with icons and subcategories.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Electronics",
      "slug": "electronics",
      "icon": "uploads/cat/elec.png",
      "children": []
    }
  ]
}
GET /products Public API

List Products (with Filters, Sort & Pagination)

Shop catalog search with comprehensive filtering and sorting options.

Request Parameters
Parameter Type Required Description
category_slug string Optional Filter by category
brand_slug string Optional Filter by brand
min_price number Optional Minimum price filter
max_price number Optional Maximum price filter
sort string Optional latest, price_asc, price_desc, popular
page integer Optional Page number (default 1)
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 101,
      "name": "Premium Basmati Rice",
      "slug": "premium-basmati-rice",
      "price": 450,
      "sale_price": 420,
      "stock": 85,
      "thumbnail": "uploads/products/rice.jpg"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 4,
    "total": 78
  }
}
GET /products/search?q={query} Public API

Quick Search Autocomplete

Fast product search by name, SKU, or keyword for search bars.

Request Parameters
Parameter Type Required Description
q string Yes Search query string
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 101,
      "name": "Premium Basmati Rice 5kg",
      "slug": "premium-basmati-rice",
      "price": 420,
      "thumbnail": "..."
    }
  ]
}
GET /products/{slug} Public API

Product Details (Standard & Combo)

Full product details including variants, image gallery, specification attributes, FAQ, and related items.

Request Parameters
Parameter Type Required Description
slug string Yes Product slug
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "id": 101,
    "name": "Organic Honey 500g",
    "slug": "organic-honey-500g",
    "price": 650,
    "discount_price": 590,
    "sku": "HONEY-01",
    "description": "100% Pure Sundarban Honey",
    "images": [
      "uploads/products/1.jpg",
      "uploads/products/2.jpg"
    ],
    "variants": [
      {
        "id": 1,
        "name": "500g",
        "price": 590,
        "stock": 20
      }
    ]
  }
}
GET /products/{product}/reviews Public API

Get Product Customer Reviews

Fetches approved reviews with star ratings and comments.

Request Parameters
Parameter Type Required Description
product integer|slug Yes Product ID or Slug
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 12,
      "rating": 5,
      "comment": "Amazing fresh quality!",
      "customer_name": "Kamrul Hasan",
      "created_at": "2026-10-01"
    }
  ]
}
POST /products/{product}/reviews Bearer Token Required

Submit Product Review

Authenticated customer submits rating and review for a purchased product.

Request Parameters
Parameter Type Required Description
rating integer Yes 1 to 5 stars
comment string Yes Review commentary
Example Request Body 
{
  "rating": 5,
  "comment": "Excellent taste and delivered within 2 hours."
}
200 OK Response 
{
  "status": "success",
  "message": "Review submitted for review approval"
}

Cart, Coupons & Checkout Flow 6 endpoints

Shipping calculations, coupon application, abandoned checkout tracking, and instant order placement.

GET /shipping-rates/active Public API

Get Available Shipping Rates

Returns active delivery charges (Inside Dhaka, Outside Dhaka, Suburbs).

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Inside Dhaka Delivery",
      "charge": 60,
      "estimated_days": "24-48 Hours"
    },
    {
      "id": 2,
      "name": "Outside Dhaka Courier",
      "charge": 120,
      "estimated_days": "3-5 Days"
    }
  ]
}
GET /payment-methods Public API

Get Active Payment Gateways

Lists enabled payment methods (Cash on Delivery, SSLCommerz, bKash, Nagad).

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": "cod",
      "name": "Cash on Delivery",
      "is_online": false
    },
    {
      "id": "sslcommerz",
      "name": "Online Payment (Cards / MFS)",
      "is_online": true
    }
  ]
}
POST /checkout/apply-coupon Public API

Validate & Apply Coupon Code

Calculates discount based on cart subtotal and coupon requirements.

Request Parameters
Parameter Type Required Description
code string Yes Coupon code
subtotal number Yes Current cart subtotal
Example Request Body 
{
  "code": "WELCOME10",
  "subtotal": 1500
}
200 OK Response 
{
  "status": "success",
  "data": {
    "code": "WELCOME10",
    "discount_amount": 150,
    "discount_type": "percentage"
  }
}
POST /checkout/incomplete-order Public API

Track Abandoned Checkout Lead

Fire & forget endpoint. Captures customer phone/cart as soon as typed to recover abandoned carts.

Request Parameters
Parameter Type Required Description
phone string Yes Customer phone
name string Optional Customer name
cart_items array Yes Items currently in cart
Example Request Body 
{
  "phone": "01812345678",
  "name": "Rahim",
  "cart_items": [
    {
      "product_id": 101,
      "qty": 2
    }
  ]
}
200 OK Response 
{
  "status": "success",
  "message": "Incomplete lead recorded"
}
POST /checkout/place-order Public API

Place Customer Order

Creates order and items in database. Supports guest checkout and registered customers.

Request Parameters
Parameter Type Required Description
name string Yes Receiver Full Name
phone string Yes 11-digit Phone
address string Yes Delivery Address
shipping_rate_id integer Yes Selected shipping rate ID
payment_method string Yes cod, sslcommerz
items array Yes List of order items
coupon_code string Optional Optional coupon code
Example Request Body 
{
  "name": "Tanvir Ahmed",
  "phone": "01712345678",
  "address": "House 12, Road 4, Dhanmondi, Dhaka",
  "shipping_rate_id": 1,
  "payment_method": "cod",
  "items": [
    {
      "product_id": 101,
      "variant_id": null,
      "quantity": 2,
      "price": 420
    }
  ]
}
200 OK Response 
{
  "status": "success",
  "message": "Order placed successfully",
  "data": {
    "order_id": 852,
    "invoice_no": "PB-2026-852",
    "grand_total": 900,
    "payment_method": "cod"
  }
}
GET /track-order?phone={phone}&invoice={invoice_no} Public API

Track Live Order Status

Live order tracking with courier status (Processing, Shipped, Delivered).

Request Parameters
Parameter Type Required Description
phone string Yes Customer phone
invoice string Optional Invoice number
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "invoice_no": "PB-2026-852",
    "status": "shipped",
    "courier_name": "Steadfast",
    "tracking_code": "ST-88992211",
    "grand_total": 900,
    "placed_at": "2026-10-10 14:30:00"
  }
}

Customer Dashboard (Authenticated) 5 endpoints

Customer profile editing, password changes, order history, invoice details, and customer reviews.

GET /dashboard/account Bearer Token Required

Get Customer Account Profile

Retrieves complete customer profile information and shipping addresses.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "id": 45,
    "name": "Tanvir Ahmed",
    "phone": "01712345678",
    "email": "tanvir@gmail.com",
    "address": "Dhanmondi, Dhaka"
  }
}
POST /dashboard/account/update Bearer Token Required

Update Customer Profile

Updates personal information (Name, Email, Default Delivery Address).

Request Parameters
Parameter Type Required Description
name string Yes Full Name
email string Optional Email address
address string Optional Default address
Example Request Body 
{
  "name": "Tanvir Ahmed",
  "email": "tanvir@gmail.com",
  "address": "Banani, Dhaka"
}
200 OK Response 
{
  "status": "success",
  "message": "Profile updated successfully"
}
POST /dashboard/account/change-password Bearer Token Required

Change Password

Updates user password by supplying current password and new password.

Request Parameters
Parameter Type Required Description
current_password string Yes Current password
new_password string Yes Minimum 6 chars
Example Request Body 
{
  "current_password": "oldPass123",
  "new_password": "newPass123"
}
200 OK Response 
{
  "status": "success",
  "message": "Password updated successfully"
}
GET /dashboard/customer/orders Bearer Token Required

List Customer Orders

Paginated history of all orders placed by the authenticated customer.

Request Parameters
Parameter Type Required Description
page integer Optional Page number
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 852,
      "invoice_no": "PB-2026-852",
      "total": 900,
      "status": "completed",
      "date": "2026-10-10"
    }
  ]
}
GET /dashboard/customer/orders/{id} Bearer Token Required

Get Order Invoice Details

Detailed view of an order with line items, variants, pricing, and courier tracking.

Request Parameters
Parameter Type Required Description
id integer Yes Order ID
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "id": 852,
    "invoice_no": "PB-2026-852",
    "status": "delivered",
    "items": [
      {
        "product_name": "Basmati Rice",
        "qty": 2,
        "price": 420,
        "total": 840
      }
    ],
    "delivery_charge": 60,
    "total": 900
  }
}

Wholesaler B2B Dashboard 2 endpoints

Bulk ordering, specialized wholesale pricing catalog, customer ledger, and direct orders.

GET /dashboard/wholesaler/products Bearer Token Required

Get Wholesaler Products & Pricing

Returns products with wholesale minimum quantities and wholesale discounted tier pricing.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 101,
      "name": "Basmati Rice 25kg Bag",
      "wholesale_price": 1800,
      "min_order_qty": 5
    }
  ]
}
POST /dashboard/wholesaler/orders Bearer Token Required

Create Bulk Wholesale Order

Places a B2B wholesale order for verified wholesalers.

Request Parameters
Parameter Type Required Description
items array Yes Product items with wholesale quantities
notes string Optional Shipping instructions
Example Request Body 
{
  "items": [
    {
      "product_id": 101,
      "quantity": 10,
      "price": 1800
    }
  ]
}
200 OK Response 
{
  "status": "success",
  "message": "Wholesale order placed successfully",
  "data": {
    "order_id": 901
  }
}

Affiliate Marketing Portal 3 endpoints

Affiliate referral links, campaign generation, commissions tracking, withdrawal requests, and payouts.

GET /dashboard/affiliate/dashboard Bearer Token Required

Affiliate Overview & Analytics

Returns metrics: Total earnings, pending commissions, referred orders, and click-throughs.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "total_earned": 4500,
    "pending_balance": 1200,
    "total_referrals": 38,
    "referral_code": "PB-AFF-772"
  }
}
GET /dashboard/affiliate/withdrawals Bearer Token Required

List Withdrawal Requests

Shows status of affiliate payout requests (Pending, Approved, Paid).

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 5,
      "amount": 2000,
      "method": "bKash",
      "account": "01712345678",
      "status": "completed",
      "date": "2026-10-05"
    }
  ]
}
POST /dashboard/affiliate/withdrawals Bearer Token Required

Request Commission Withdrawal

Submits a withdrawal request for earned affiliate balance.

Request Parameters
Parameter Type Required Description
amount number Yes Withdrawal amount (Tk)
payment_method string Yes bKash, Nagad, Bank Transfer
account_number string Yes Target account number
Example Request Body 
{
  "amount": 1500,
  "payment_method": "bKash",
  "account_number": "01712345678"
}
200 OK Response 
{
  "status": "success",
  "message": "Withdrawal request submitted successfully"
}

Content, Blogs & Global Settings 3 endpoints

Site configuration, social links, blog articles, SEO metadata, and legal policies.

GET /settings Public API

Get General Site Settings

Returns store metadata, logo URL, contact phone/email, address, and social links.

Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "site_name": "Positive Bazar",
    "phone": "+8801700000000",
    "email": "support@positivebazar.com",
    "currency": "Tk",
    "logo": "uploads/settings/logo.png"
  }
}
GET /blogs Public API

List Blog Articles

Returns published articles with pagination and category filtering.

Request Parameters
Parameter Type Required Description
category string Optional Category slug
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": [
    {
      "id": 10,
      "title": "Healthy Eating with Organic Groceries",
      "slug": "healthy-eating",
      "thumbnail": "uploads/blogs/1.jpg"
    }
  ]
}
GET /custom-pages/{slug} Public API

Get Custom Page Content

Returns rich HTML content for terms, privacy-policy, return-policy, about-us.

Request Parameters
Parameter Type Required Description
slug string Yes Page slug (e.g. privacy-policy)
Example Request Body 
// No request body required (GET request)
200 OK Response 
{
  "status": "success",
  "data": {
    "title": "Privacy Policy",
    "content": "
We take customer privacy seriously...
"
  }
}

Payment Gateways & Courier Webhooks 3 endpoints

SSLCommerz payment processing, transaction validation, and automated courier webhook callbacks.

POST /payment/sslcommerz/initiate Public API

Initiate SSLCommerz Payment Session

Creates gateway session and returns gateway URL for redirect.

Request Parameters
Parameter Type Required Description
order_id integer Yes Order ID
Example Request Body 
{
  "order_id": 852
}
200 OK Response 
{
  "status": "success",
  "data": {
    "gateway_url": "https://sandbox.sslcommerz.com/gwprocess/v4/api.php?..."
  }
}
POST /webhooks/steadfast Public API

Steadfast Courier Status Webhook

Automated webhook called by Steadfast to update live delivery status.

Example Request Body 
{
  "consignment_id": "ST-88992211",
  "status": "delivered"
}
200 OK Response 
{
  "status": "success"
}
POST /webhooks/pathao Public API

Pathao Courier Status Webhook

Automated webhook called by Pathao to update delivery and return tracking.

Example Request Body 
{
  "consignment_id": "PT-9988",
  "event": "order.delivered"
}
200 OK Response 
{
  "status": "success"
}
Access granted. Welcome to API Portal.