bPOS REST API Documentation

Getting Started

Base URL

https://your-domain.com/api/v1

Rate Limiting

60 requests per minute per API key

Response Format

All responses are in JSON format with the following structure:

{
  "success": true,
  "message": "Success message",
  "data": { ... },
  "meta": { ... }  // For paginated responses
}

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Header Format

X-API-Key: your-api-key-here

Alternative format:

Authorization: Bearer your-api-key-here

Important: Keep your API key secure and never share it publicly.

Products API

GET /products

List all products with pagination and optional filters

Query Parameters

Parameter	Type	Required	Description
per_page	integer	No	Items per page (default: 20, max: 100)
page	integer	No	Page number (default: 1)
category	string/integer	No	Filter by category name or ID
brand	string/integer	No	Filter by brand name or ID
search	string	No	Search by product name or code
featured	boolean	No	Filter featured products (true/false)
include_stock	boolean	No	Include stock information (true/false)
branch_id	integer	No	Branch ID for stock (required if include_stock=true)

Example Request

GET /api/v1/products?per_page=10&include_stock=true&branch_id=1

Example Response

{
  "success": true,
  "message": "Products retrieved successfully",
  "data": [
    {
      "code": "PROD-001",
      "parent_code": null,
      "name": "iPhone 15 Pro",
      "sinhala_name": null,
      "description": "Latest iPhone model",
      "category": {
        "id": 1,
        "name": "Mobile Phones"
      },
      "brand": {
        "id": 5,
        "name": "Apple"
      },
      "price": {
        "amount": 125000.00,
        "currency": "LKR",
        "formatted": "125,000.00 LKR"
      },
      "marked_price": null,
      "images": [
        "https://your-domain.com/images/iphone15.jpg",
        "https://your-domain.com/images/iphone15-2.jpg"
      ],
      "custom_fields": null,
      "is_featured": true,
      "plu_number": "PLU-001",
      "weight": 221,
      "weight_unit": "g",
      "stock_quantity": 15
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 150
  }
}

GET /products/search

Search products (autocomplete)

Query Parameters

Parameter	Type	Required	Description
term	string	Yes	Search term
limit	integer	No	Max results (default: 10, max: 50)

Example Request

GET /api/v1/products/search?term=iphone&limit=10

Example Response

{
  "success": true,
  "message": "Search results retrieved successfully",
  "data": [
    {
      "code": "PROD-001",
      "name": "iPhone 15 Pro",
      "image": "https://your-domain.com/images/iphone15.jpg"
    }
  ]
}

GET /products/{code}

Get single product details by product code

Query Parameters

Parameter	Type	Required	Description
include_stock	boolean	No	Include stock information (true/false)
branch_id	integer	No	Branch ID for stock (required if include_stock=true)

Example Request

GET /api/v1/products/PROD-001?include_stock=true&branch_id=1

Example Response

{
  "success": true,
  "message": "Product retrieved successfully",
  "data": {
    "code": "PROD-001",
    "parent_code": null,
    "name": "iPhone 15 Pro",
    "sinhala_name": null,
    "description": "Latest iPhone model",
    "category": {
      "id": 1,
      "name": "Mobile Phones"
    },
    "brand": {
      "id": 5,
      "name": "Apple"
    },
    "price": {
      "amount": 125000.00,
      "currency": "LKR",
      "formatted": "125,000.00 LKR"
    },
    "marked_price": null,
    "images": [
      "https://your-domain.com/images/iphone15.jpg",
      "https://your-domain.com/images/iphone15-2.jpg"
    ],
    "custom_fields": null,
    "is_featured": true,
    "plu_number": "PLU-001",
    "weight": 221,
    "weight_unit": "g",
    "stock_quantity": 15
  }
}

Categories API

GET /categories

List all categories

Example Response

{
  "success": true,
  "message": "Categories retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Electronics",
      "other_name": null,
      "slug": "electronics",
      "parent_id": null,
      "order": 1,
      "is_service": false,
      "main": 1,
      "subcategories": [
        {
          "id": 10,
          "name": "Mobile Phones",
          "other_name": null,
          "slug": "mobile-phones",
          "parent_id": 1,
          "order": null,
          "subcategories": [],
          "product_count": null
        }
      ],
      "product_count": null
    }
  ]
}

GET /categories/{id}

Get a single category with its subcategories

Example Response

{
  "success": true,
  "message": "Category retrieved successfully",
  "data": {
    "id": 1,
    "name": "Electronics",
    "other_name": null,
    "slug": "electronics",
    "parent_id": null,
    "order": 1,
    "is_service": false,
    "main": 1,
    "subcategories": [
      {
        "id": 10,
        "name": "Mobile Phones",
        "other_name": null,
        "slug": "mobile-phones",
        "parent_id": 1,
        "order": null,
        "subcategories": [],
        "product_count": null
      }
    ],
    "product_count": null
  }
}

GET /categories/{id}/subcategories

Get subcategories of a specific category

Example Response

{
  "success": true,
  "message": "Subcategories retrieved successfully",
  "data": [
    {
      "id": 10,
      "name": "Mobile Phones",
      "other_name": null,
      "slug": "mobile-phones",
      "parent_id": 1,
      "order": 2,
      "subcategories": [],
      "product_count": null
    },
    {
      "id": 11,
      "name": "Laptops",
      "other_name": null,
      "slug": "laptops",
      "parent_id": 1,
      "order": 3,
      "subcategories": [],
      "product_count": null
    }
  ]
}

Brands API

GET /brands

List all brands

Example Response

{
  "success": true,
  "message": "Brands retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Apple",
      "slug": "apple",
      "logo": "https://your-domain.com/logos/apple.png"
    }
  ]
}

Orders API

GET /orders

List all orders with pagination and filters

Query Parameters

Parameter	Type	Required	Description
per_page	integer	No	Items per page (default: 20, max: 100)
page	integer	No	Page number (default: 1)
status	string	No	Filter by order status
customer_id	integer	No	Filter by customer ID
start_date	date (Y-m-d)	No	Filter orders from this date
end_date	date (Y-m-d)	No	Filter orders until this date

Example Request

GET /api/v1/orders?per_page=20&status=pending&start_date=2026-01-01&end_date=2026-01-31

Example Response

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": [
    {
      "id": 12345,
      "date": "2026-01-22",
      "status": "pending",
      "customer": {
        "id": 123,
        "name": "John Doe"
      },
      "total": 5400.00,
      "items_count": 3
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 150
  }
}

POST /orders

Create a new order

Request Parameters

Parameter	Type	Required	Description
customer_id	integer	Yes	Customer ID
items	array	Yes	Array of order items (min: 1)
items.*.product_code	string	Yes	Product code
items.*.quantity	integer	Yes	Quantity (min: 1)
items.*.price	numeric	No	Custom price (optional)
delivery_address_id	integer	No	Delivery address ID
delivery_date	date	No	Delivery date
payment_type	integer	No	Payment type (1=COD, 2=Card, 3=Bank)
notes	string	No	Order notes
discount	numeric	No	Manual discount (min: 0)

Example Request

{
  "customer_id": 123,
  "items": [
    {
      "product_code": "PROD-001",
      "quantity": 2,
      "price": 2500.00
    },
    {
      "product_code": "PROD-002",
      "quantity": 1
    }
  ],
  "delivery_address_id": 45,
  "delivery_date": "2026-01-25",
  "payment_type": 1,
  "notes": "Please deliver before 5 PM",
  "discount": 100.00
}

Example Response

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": 12345,
    "date": "2026-01-22",
    "status": "pending",
    "customer": {
      "id": 123,
      "name": "John Doe"
    },
    "total": 5400.00,
    "shipping": 400.00
  }
}

Customers API

GET /customers

List all customers with pagination and search

Query Parameters

Parameter	Type	Required	Description
per_page	integer	No	Items per page (default: 20, max: 100)
page	integer	No	Page number (default: 1)
search	string	No	Search by name, email, or phone

Example Request

GET /api/v1/customers?per_page=20&search=john

Example Response

{
  "success": true,
  "message": "Customers retrieved successfully",
  "data": [
    {
      "id": 456,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+94771234567",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 85
  }
}

POST /customers

Create a new customer

Request Parameters

Parameter	Type	Required	Description
f_name	string	Yes	First name (max: 255)
l_name	string	No	Last name (max: 255)
email	email	Yes	Email address (must be unique)
phone	string	Yes	Phone number
address	string	No	Address
city_id	numeric	No	City ID
lat	numeric	No	Latitude
lng	numeric	No	Longitude
custom_fields	string	No	Custom fields data

Example Request

{
  "f_name": "John",
  "l_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+94771234567",
  "address": "123 Main Street, Colombo",
  "city_id": 1,
  "lat": 6.9271,
  "lng": 79.8612,
  "custom_fields": "VIP Customer"
}

Example Response

{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": 456,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+94771234567",
    "customer_id": 789,
    "created_at": "2026-01-22T19:05:00Z"
  }
}

Customer Addresses API

GET /customers/{id}/addresses

Get all addresses for a specific customer

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "address": "123 Main Street",
      "address_line_1": "Apartment 4B",
      "address_line_2": "Near Central Park",
      "city": "Colombo",
      "province": "Western",
      "country": "Sri Lanka",
      "postal_code": "00100",
      "contact_person": "John Doe",
      "company_name": "ABC Company",
      "contact": {
        "id": 5,
        "number": "+94771234567"
      },
      "lat": 6.9271,
      "lng": 79.8612
    }
  ]
}

POST /customers/{id}/addresses

Create a new address for a customer

Request Parameters

Parameter	Type	Required	Description
address	string	Yes	Main address
contact	string	Yes	Contact phone number
address_line_1	string	No	Address line 1
address_line_2	string	No	Address line 2
city	string	No	City
province	string	No	Province/State
country	string	No	Country
postal_code	string	No	Postal/ZIP code (max: 10)
contact_person	string	No	Contact person name
company_name	string	No	Company name
lat	numeric	No	Latitude
lng	numeric	No	Longitude

Example Request

{
  "address": "456 Park Avenue",
  "address_line_1": "Floor 3",
  "address_line_2": "Suite 301",
  "contact": "+94771234567",
  "contact_person": "Jane Smith",
  "company_name": "XYZ Corp",
  "city": "Kandy",
  "province": "Central",
  "country": "Sri Lanka",
  "postal_code": "20000",
  "lat": 7.2906,
  "lng": 80.6337
}

Example Response

{
  "success": true,
  "message": "Address created successfully",
  "data": {
    "id": 2,
    "address": "456 Park Avenue",
    "city": "Kandy",
    "contact_person": "Jane Smith"
  }
}

PATCH /customers/{customerId}/addresses/{addressId}

Update an existing customer address

Request Parameters

Same parameters as POST /customers/{id}/addresses (all optional for PATCH)

Example Request

{
  "address": "456 Park Avenue Updated",
  "postal_code": "20001",
  "contact_person": "Jane Smith Updated"
}

Example Response

{
  "success": true,
  "message": "Address updated successfully",
  "data": {
    "id": 2,
    "address": "456 Park Avenue Updated",
    "postal_code": "20001",
    "contact_person": "Jane Smith Updated"
  }
}

Reports API

GET /reports/sales

Get sales report with date range and filters

Query Parameters

Parameter	Type	Required	Description
start_date	date (Y-m-d)	Yes	Report start date
end_date	date (Y-m-d)	Yes	Report end date (must be >= start_date)
branch_id	integer	No	Filter by branch
customer_id	integer	No	Filter by customer
product_code	string	No	Filter by product code
category	string	No	Filter by category
brand	string	No	Filter by brand
agent_id	integer	No	Filter by sales agent
page	integer	No	Page number (min: 1, default: 1)
per_page	integer	No	Items per page (min: 1, max: 100, default: 15)

Example Request

GET /api/v1/reports/sales?start_date=2026-01-01&end_date=2026-01-31&branch_id=1&page=1&per_page=20

Example Response

{
  "success": true,
  "message": "Sales report retrieved successfully",
  "data": [
    {
      "date": "2026-01-22",
      "product_name": "iPhone 15 Pro",
      "sales_quantity": 5,
      "sales_total": 625000.00,
      "profit": 125000.00
    }
  ],
  "meta": {
    "summary": {
      "total_sales": 625000.00,
      "total_profit": 125000.00
    }
  }
}

WooCommerce Plugin

bPOS for WooCommerce

Official WordPress plugin to sync your bPOS ERP with WooCommerce. Automatically syncs products, categories, brands, stock levels, customers, and orders.

Download v1.0.0

Features

Product sync (name, price, images, weight, categories, brands)

Category & brand sync with hierarchy

Real-time stock level sync per branch

Customer sync (WooCommerce ↔ ERP)

Order sync with status mapping

Automated cron-based background sync

Image downloading & attachment

Rate limiting & sync logging

Installation

Download the bpos-v1.0.0.zip file
In WordPress admin, go to Plugins → Add New → Upload Plugin
Upload the zip file and click Install Now
Activate the plugin
Go to bPOS → Settings and enter your API URL and API Key
Configure your Branch ID and sync preferences
Run your first sync from bPOS → Sync

Required Settings

Setting	Description
API URL	Your bPOS API base URL (e.g., https://your-domain.com)
API Key	Your X-API-Key for authentication
Branch ID	Branch ID for stock sync (matches branch_id parameter in API)