Branch Management

Create Branch

Creates a new physical location for the authenticated account.

Endpoint

POST /api/pos/branches

Request Payload

Field	Type	Required	Description
`name`	string	Yes	Branch name (max 100 chars)
`external_id`	string	No	External system ID (max 100 chars)
`address`	object	No	Physical address
`address.street`	string	No	Street address (max 200 chars)
`address.city`	string	No	City (max 100 chars)
`address.state`	string	No	State (max 100 chars)
`address.country`	string	No	Country (default: "Mexico", max 100 chars)
`address.postal_code`	string	No	Postal code (max 20 chars)
`address.latitude`	number	No	Latitude (-90 to 90)
`address.longitude`	number	No	Longitude (-180 to 180)
`contact`	object	No	Contact information
`contact.email`	string	No	Contact email (max 255 chars)
`contact.phone`	string	No	Contact phone (max 30 chars)
`contact.manager_name`	string	No	Manager name (max 100 chars)
`operating_hours`	object	No	Operating hours per day
`operating_hours.[day]`	object	No	Hours for specific day (monday-sunday)
`operating_hours.[day].open`	string	No	Opening time (HH:MM format)
`operating_hours.[day].close`	string	No	Closing time (HH:MM format)
`operating_hours.[day].is_closed`	boolean	No	Whether closed on this day
`timezone`	string	No	Timezone (default: "America/Mexico_City")
`status`	string	No	Status: `active`, `inactive`, `paused` (default: "active")
`settings`	object	No	Branch settings
`settings.auto_close_registers`	boolean	No	Auto-close registers at end of day
`settings.require_cash_reconciliation`	boolean	No	Require cash count on close
`settings.default_currency`	string	No	Default currency (3 chars, uppercase)
`settings.receipt_header`	string	No	Receipt header text (max 500 chars)
`settings.receipt_footer`	string	No	Receipt footer text (max 500 chars)
`metadata`	object	No	Custom metadata

Example Response

{
  "message": "Branch created successfully",
  "data": {
    "_id": "60b7f96f4118eb4370469d19",
    "name": "Downtown Store",
    "status": "active"
  }
}

Get All Branches

Retrieves all branches for the authenticated account.

Endpoint

GET /api/pos/branches

Query parameters

Parameter	Type	Description
`status`	string	Filter by status
`city`	string	Filter by city
`state`	string	Filter by state
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)

Response

{
  "data": [...],
  "pagination": {
    "total": 10,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Get Branch by ID

Retrieves a specific branch.

Endpoint

GET /api/pos/branches/:id

Response

{
  "data": {
    "_id": "...",
    "name": "Downtown Store",
    ...
  }
}

Update Branch

Updates an existing branch.

Endpoint

PUT /api/pos/branches/:id

Request Payload

Same fields as Create Branch (all optional)

Response

{
  "message": "Branch updated successfully",
  "data": { ... }
}

Delete Branch

Soft-deletes a branch.

Endpoint

DELETE /api/pos/branches/:id

Request Body:

Field	Type	Required	Description
`force`	boolean	No	Force delete even with active registers (default: false)
`reason`	string	No	Deletion reason (max 500 chars)

Response

{
  "message": "Branch deleted successfully",
  "data": {
    "id": "...",
    "deleted_at": "2025-12-01T..."
  }
}

Restore Branch

Restores a soft-deleted branch.

Endpoint

POST /api/pos/branches/:id/restore

Response

{
  "message": "Branch restored successfully",
  "data": { ... }
}

Check Branch Status

Verifies if a specific branch is currently open based on its configured operating hours.

Endpoint

GET /api/pos/branches/:id/status

Query Parameters

check_time (String): ISO date to check (defaults to current time).

Response

{
  "data": {
    "is_open": true,
    "branch_name": "Downtown Store",
    "operating_hours": {
      "open": "09:00",
      "close": "21:00",
      "is_closed": false
    },
    "current_time": "14:30",
    "checked_at": "2025-12-01T14:30:00.000Z"
  }
}