Skip to main content
Branches represent physical store locations for a merchant. Each branch can have its own POS terminals and payment settings.

​
Create Branch

POST /v1/branches
Requires a valid Bearer token in the Authorization header.

​
Request Body

​
name
string
required
Branch display name (e.g., Colombo Main Store).
​
address
string
required
Physical address of the branch.
​
city
string
required
City where the branch is located.
​
phone
string
Branch contact phone number.

​
Example Request

{
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678"
}

​
Example Response (201)

{
  "id": "branch_abc123",
  "merchantId": "merch_abc123",
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678",
  "status": "active",
  "createdAt": "2026-03-26T10:00:00Z"
}

​
List Branches

GET /v1/branches
Returns all branches for the authenticated merchant.

​
Query Parameters

​
page
integer
default:"1"
Page number.
​
limit
integer
default:"20"
Items per page (max 100).

​
Example Response (200)

{
  "data": [
    {
      "id": "branch_abc123",
      "name": "Colombo Main Store",
      "address": "123 Galle Road, Colombo 03",
      "city": "Colombo",
      "status": "active",
      "createdAt": "2026-03-26T10:00:00Z"
    },
    {
      "id": "branch_def456",
      "name": "Kandy Branch",
      "address": "45 Peradeniya Road, Kandy",
      "city": "Kandy",
      "status": "active",
      "createdAt": "2026-03-20T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

​
Get Branch

GET /v1/branches/{id}

​
Path Parameters

​
id
string
required
The branch identifier (e.g., branch_abc123).

​
Example Response (200)

{
  "id": "branch_abc123",
  "merchantId": "merch_abc123",
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678",
  "status": "active",
  "createdAt": "2026-03-26T10:00:00Z",
  "updatedAt": "2026-03-26T10:00:00Z"
}

​
Delete Branch

DELETE /v1/branches/{id}
Permanently deletes a branch. Active POS terminals associated with the branch will be deactivated.

​
Path Parameters

​
id
string
required
The branch identifier (e.g., branch_abc123).

​
Example Response (200)

{
  "message": "Branch deleted successfully"
}

​
Error Responses

404 Not Found
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Branch not found"
  }
}