Overview Branches represent individual locations or outlets within an organization. Each branch can have its own menu, tables, staff, and settings while sharing the organization’s overall configuration.
Base URL https://api.restai.com/v1/branches
Authentication All branch endpoints require:
Bearer token authentication
Tenant middleware (automatically scopes to current organization)
Authorization: Bearer < your_toke n >
Permissions
branch:read - View branchesbranch:create - Create new branchesbranch:update - Modify branch details
Branch Object Unique identifier for the branch
ID of the parent organization
Branch name (2-255 characters)
URL-friendly identifier (lowercase letters, numbers, hyphens only)
Physical address (max 500 characters)
Contact phone number (max 20 characters)
IANA timezone identifier (e.g., “America/Lima”)
ISO 4217 currency code (3 characters, e.g., “PEN”)
Tax rate in basis points (e.g., 1800 = 18%)
When the branch was created
When the branch was last updated
Endpoints List Branches
GET /branches Retrieve all branches for the current organization
Required Permission: branch:readRequest: curl https://api.restai.com/v1/branches \ -H "Authorization: Bearer <token>"
Response: { "success" : true , "data" : [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "organization_id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Sucursal Centro" , "slug" : "centro" , "address" : "Av. Principal 123, Lima" , "phone" : "+51 999 888 777" , "timezone" : "America/Lima" , "currency" : "PEN" , "tax_rate" : 1800 , "created_at" : "2024-01-20T10:00:00Z" , "updated_at" : "2024-02-15T14:30:00Z" } ] }
Create Branch
POST /branches Create a new branch in the current organization
Required Permission: branch:createBody Parameters: Branch name (2-255 characters)
URL-friendly identifier (2-100 characters, lowercase letters, numbers, and hyphens only)
Physical address (max 500 characters)
Contact phone number (max 20 characters)
timezone
string
default: "America/Lima"
IANA timezone identifier
ISO 4217 currency code (exactly 3 characters)
Tax rate in basis points (0-10000). Example: 1800 = 18%
Request: curl -X POST https://api.restai.com/v1/branches \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Sucursal Miraflores", "slug": "miraflores", "address": "Av. Larco 450, Miraflores, Lima", "phone": "+51 999 777 888", "timezone": "America/Lima", "currency": "PEN", "taxRate": 1800 }'
Response (201 Created): { "success" : true , "data" : { "id" : "660e9511-f39c-52e5-b827-557766551111" , "organization_id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Sucursal Miraflores" , "slug" : "miraflores" , "address" : "Av. Larco 450, Miraflores, Lima" , "phone" : "+51 999 777 888" , "timezone" : "America/Lima" , "currency" : "PEN" , "tax_rate" : 1800 , "created_at" : "2024-03-02T10:30:00Z" , "updated_at" : "2024-03-02T10:30:00Z" } }
Error Responses: // 409 Conflict - Slug already exists { "success" : false , "error" : { "code" : "CONFLICT" , "message" : "El slug de sucursal ya existe" } }
Get Branch
GET /branches/:id Retrieve a specific branch by ID
Required Permission: branch:readPath Parameters: Request: curl https://api.restai.com/v1/branches/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <token>"
Response: { "success" : true , "data" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "organization_id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Sucursal Centro" , "slug" : "centro" , "address" : "Av. Principal 123, Lima" , "phone" : "+51 999 888 777" , "timezone" : "America/Lima" , "currency" : "PEN" , "tax_rate" : 1800 , "created_at" : "2024-01-20T10:00:00Z" , "updated_at" : "2024-02-15T14:30:00Z" } }
Error Response: // 404 Not Found { "success" : false , "error" : { "code" : "NOT_FOUND" , "message" : "Sucursal no encontrada" } }
Update Branch
PATCH /branches/:id Update branch details. All fields are optional.
Required Permission: branch:updatePath Parameters: Body Parameters (all optional): Branch name (2-255 characters)
URL-friendly identifier (2-100 characters)
Physical address (max 500 characters)
Contact phone number (max 20 characters)
ISO 4217 currency code (3 characters)
Tax rate in basis points (0-10000)
Request: curl -X PATCH https://api.restai.com/v1/branches/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Sucursal Centro - Plaza Mayor", "phone": "+51 999 888 999", "taxRate": 1600 }'
Response: { "success" : true , "data" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "organization_id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Sucursal Centro - Plaza Mayor" , "slug" : "centro" , "address" : "Av. Principal 123, Lima" , "phone" : "+51 999 888 999" , "timezone" : "America/Lima" , "currency" : "PEN" , "tax_rate" : 1600 , "created_at" : "2024-01-20T10:00:00Z" , "updated_at" : "2024-03-02T11:00:00Z" } }
The tax_rate field is stored in basis points to avoid floating-point precision issues:
1 basis point = 0.01%
1800 basis points = 18%
1600 basis points = 16%
To convert: tax_percentage * 100 = tax_rate
When displaying tax rates to users, divide the tax_rate by 100 to get the percentage.
Slug Uniqueness The slug field must be unique within an organization. It’s commonly used for:
Creating user-friendly URLs
QR code generation
Branch identification in customer-facing interfaces
Changing a branch slug may break existing QR codes and customer links. Update with caution.