Skip to main content
The Settings API allows you to configure organization-level and branch-level settings for your RestAI account.

​
Organization vs Branch Settings

  • Organization Settings: Apply globally across all branches (e.g., company name, logo)
  • Branch Settings: Specific to each location (e.g., address, tax rate, timezone)

​
Get Organization Settings

GET /api/settings/org

Retrieve current organization settings
Authentication Required: Yes (Bearer token) Request: 
curl https://api.restai.com/v1/api/settings/org \
  -H "Authorization: Bearer <token>"
Response: 
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Restaurante La Buena Mesa",
    "slug": "la-buena-mesa",
    "logo_url": "https://example.com/logo.png",
    "settings": {
      "theme_color": "#FF6B35",
      "enable_loyalty": true
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-03-01T14:30:00Z"
  }
}
Error Responses: 
// 404 Not Found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Organizacion no encontrada"
  }
}

​
Organization Object

​
id
string (uuid)
Unique organization identifier
​
name
string
Organization name (2-255 characters)
​
slug
string
URL-safe identifier (read-only after creation)
​
logo_url
string
URL to organization logo image
​
settings
object
Custom settings object for organization-wide configuration
​
created_at
string (datetime)
Creation timestamp
​
updated_at
string (datetime)
Last update timestamp

​
Update Organization Settings

PATCH /api/settings/org

Update organization settings (all fields optional)
Required Permission: org:update Body Parameters:
​
name
string
Organization name (2-255 characters)
​
logoUrl
string
URL to organization logo (must be valid URL or null)
​
settings
object
Custom settings object (arbitrary key-value pairs)
Request: 
curl -X PATCH https://api.restai.com/v1/api/settings/org \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "La Buena Mesa - Central",
    "logoUrl": "https://cdn.example.com/new-logo.png",
    "settings": {
      "theme_color": "#2E86AB",
      "enable_loyalty": true,
      "default_language": "es"
    }
  }'
Response: 
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "La Buena Mesa - Central",
    "slug": "la-buena-mesa",
    "logo_url": "https://cdn.example.com/new-logo.png",
    "settings": {
      "theme_color": "#2E86AB",
      "enable_loyalty": true,
      "default_language": "es"
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-03-02T09:15:00Z"
  }
}

​
Get Branch Settings

GET /api/settings/branch

Retrieve current branch settings
Authentication Required: Yes (Bearer token with branch context) Request: 
curl https://api.restai.com/v1/api/settings/branch \
  -H "Authorization: Bearer <token>"
Response: 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sede Miraflores",
    "slug": "miraflores",
    "address": "Av. Larco 1234, Miraflores, Lima",
    "phone": "+51 1 234-5678",
    "tax_rate": 1800,
    "timezone": "America/Lima",
    "currency": "PEN",
    "settings": {
      "inventory_enabled": true,
      "waiter_table_assignment_enabled": false
    },
    "created_at": "2024-01-15T10:05:00Z",
    "updated_at": "2024-03-01T16:20:00Z"
  }
}
Error Responses: 
// 400 Bad Request - No branch context
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Branch ID requerido"
  }
}

// 404 Not Found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Sede no encontrada"
  }
}

​
Branch Object

​
id
string (uuid)
Unique branch identifier
​
organization_id
string (uuid)
Parent organization ID
​
name
string
Branch name (2-255 characters)
​
slug
string
URL-safe identifier (read-only after creation)
​
address
string
Physical address (max 500 characters)
​
phone
string
Contact phone number (max 20 characters)
​
tax_rate
integer
Tax rate in basis points (e.g., 1800 = 18%)
​
timezone
string
IANA timezone identifier (e.g., “America/Lima”)
​
currency
string
ISO 4217 currency code (e.g., “PEN”, “USD”)
​
settings
object
Branch-specific feature toggles and configuration
​
created_at
string (datetime)
Creation timestamp
​
updated_at
string (datetime)
Last update timestamp

​
Update Branch Settings

PATCH /api/settings/branch

Update branch settings (all fields optional)
Required Permission: settings:* Body Parameters:
​
name
string
Branch name (2-255 characters)
​
address
string
Physical address (max 500 characters)
​
phone
string
Contact phone number (max 20 characters)
​
taxRate
integer
Tax rate in basis points (0-10000, e.g., 1800 = 18%)
​
timezone
string
IANA timezone identifier
​
currency
string
ISO 4217 currency code (3 characters)
​
settings
object
Custom settings object (arbitrary key-value pairs)
​
inventoryEnabled
boolean
Enable inventory management for this branch
​
waiterTableAssignmentEnabled
boolean
Enable waiter table assignment feature
Request: 
curl -X PATCH https://api.restai.com/v1/api/settings/branch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sede Miraflores - Principal",
    "address": "Av. Larco 1234, Miraflores, Lima 15074",
    "phone": "+51 1 234-5679",
    "taxRate": 1800,
    "timezone": "America/Lima",
    "currency": "PEN",
    "inventoryEnabled": true,
    "waiterTableAssignmentEnabled": true
  }'
Response: 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sede Miraflores - Principal",
    "slug": "miraflores",
    "address": "Av. Larco 1234, Miraflores, Lima 15074",
    "phone": "+51 1 234-5679",
    "tax_rate": 1800,
    "timezone": "America/Lima",
    "currency": "PEN",
    "settings": {
      "inventory_enabled": true,
      "waiter_table_assignment_enabled": true
    },
    "created_at": "2024-01-15T10:05:00Z",
    "updated_at": "2024-03-02T10:30:00Z"
  }
}
Error Responses: 
// 400 Bad Request - No branch context
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Branch ID requerido"
  }
}

​
Tax Rate Calculation

The tax_rate field uses basis points (1/100th of a percent):
  • 1800 = 18% (Peru IGV)
  • 1600 = 16% (Mexico IVA)
  • 2100 = 21% (Argentina IVA)
  • 1900 = 19% (Chile IVA)
Formula: tax_rate / 10000 = decimal rate Example: 
const taxRate = 1800; // from API
const taxPercent = taxRate / 100; // 18%
const taxDecimal = taxRate / 10000; // 0.18

const subtotal = 10000; // 100.00 PEN in cents
const taxAmount = Math.round(subtotal * taxDecimal); // 1800 (18.00 PEN)
const total = subtotal + taxAmount; // 11800 (118.00 PEN)

​
Feature Toggles

​
Inventory Management

Control whether inventory tracking is enabled: 
curl -X PATCH https://api.restai.com/v1/api/settings/branch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "inventoryEnabled": true }'
When enabled, the /api/inventory endpoints become available.

​
Waiter Table Assignment

Control whether waiters can be assigned to specific tables: 
curl -X PATCH https://api.restai.com/v1/api/settings/branch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "waiterTableAssignmentEnabled": true }'
When enabled, the /api/tables/:id/assignments endpoints become available.

​
Custom Settings

Both organization and branch settings support arbitrary JSON objects in the settings field: 
curl -X PATCH https://api.restai.com/v1/api/settings/branch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "printer_ip": "192.168.1.100",
      "auto_print_kitchen": true,
      "receipt_footer": "¡Gracias por su visita!",
      "payment_methods": ["cash", "card", "yape"],
      "max_table_session_hours": 4
    }
  }'
The settings object is merged with existing settings when you use inventoryEnabled or waiterTableAssignmentEnabled. If you provide a settings object directly, it will replace the entire settings object.

​
Best Practices

  1. Tax Rates: Always store tax rates in basis points to avoid floating-point precision issues
  2. Timezones: Use IANA timezone identifiers for consistent date/time handling across regions
  3. Currency: Use ISO 4217 codes and store monetary amounts in the smallest unit (cents/centimos)
  4. Logo URLs: Upload logos using the /api/uploads endpoint, then reference the returned URL
  5. Feature Toggles: Use inventoryEnabled and waiterTableAssignmentEnabled for first-class features; use settings object for custom configuration

​
Multi-Branch Organizations

For organizations with multiple branches: 
// Organization-level settings (shared)
{
  "name": "La Buena Mesa",
  "logoUrl": "https://cdn.example.com/logo.png",
  "settings": {
    "theme_color": "#FF6B35",
    "enable_loyalty": true
  }
}

// Branch-level settings (per location)
[
  {
    "name": "Sede Miraflores",
    "address": "Av. Larco 1234",
    "taxRate": 1800,
    "timezone": "America/Lima",
    "currency": "PEN"
  },
  {
    "name": "Sede San Isidro",
    "address": "Av. Conquistadores 567",
    "taxRate": 1800,
    "timezone": "America/Lima",
    "currency": "PEN"
  }
]
Keep branding and loyalty settings at the organization level, while keeping tax rates, addresses, and operational settings at the branch level.

Build docs developers (and LLMs) love

Get started for freeTalk to us