Service Scoping

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

What Is Service Scoping?

Service scoping determines whether a service is available across all locations or restricted to a specific location. This gives you flexibility to manage both standardized offerings and location-specific services.

Scope Options

Services can have one of two scope values:

• COMPANY – Service is defined once and available at all locations
• LOCATION – Service exists only at a specific location

The scope field is set when creating a service and determines its visibility and management.

Company Scope

When to Use

Company-scoped services are ideal for:

• Standardized offerings – Services that should be consistent across all locations
• Franchises or chains – Same menu everywhere
• Centralized management – Update once, apply everywhere
• Shared resource pools – Resources can deliver the service at any location

How It Works

When you create a company-scoped service:

{
  "name": "Basic Consultation",
  "duration": 30,
  "scope": "COMPANY"
}

The service:

• Appears in availability searches for any location (if resources are assigned)
• Can be booked at any location where eligible resources exist
• Uses one definition but respects per-location resource availability
• Simplifies management (one service record for all locations)

Resource Assignment

Company-scoped services still require resources to be linked at each location:

1. Create service with scope: COMPANY
2. Link resources to the service at each location
3. Service appears in availability where resources exist

Example:

A dental chain has a "Cleaning" service (company-scoped). It's available at:

• Downtown office – 3 hygienists linked to the service
• Suburban office – 2 hygienists linked
• New location (not yet operational) – No resources linked, service won't appear in availability yet

The service definition is centralized, but actual bookability depends on resource assignments per location.

Updating Company-Scoped Services

Changes to company-scoped services affect all locations:

curl -X PUT https://v3.onsched.com/v3/service/SERVICE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 45,
    "padding": 15
  }'

After this update, the "Cleaning" service has 45-minute duration and 15-minute padding everywhere.

Use cautiously: Changing duration or padding can disrupt existing schedules.

Location Scope

When to Use

Location-scoped services are ideal for:

• Unique offerings – Specialized services only certain locations provide
• Pilot programs – Testing new services before rolling out company-wide
• Compliance variations – Different regulations at different locations
• Equipment limitations – Services requiring location-specific equipment

How It Works

When you create a location-scoped service:

{
  "name": "Orthodontics Consultation",
  "duration": 60,
  "scope": "LOCATION",
  "CompanyId": "company-uuid",
  "LocationId": "location-uuid"
}

The service:

• Only appears in availability for the specified location
• Can only be booked at that location
• Won't show up in searches or lists for other locations
• Managed independently per location

Independence

Location-scoped services are completely independent. You can have:

• Different services with the same name at different locations
• Different configurations (duration, pricing, etc.) per location
• Location-specific resource links

Example:

A fitness studio has location-scoped services:

• Downtown location – "Advanced Boxing" (90 min, specialized ring required)
• Suburban location – "Family Yoga" (60 min, family-friendly studio)
• Airport location – "Express Workout" (30 min, 24/7 availability)

None of these services appear at other locations—they're tailored to each facility's unique offerings.

Scope Comparison

Choosing the Right Scope

Ask these questions:

Should this service be identical everywhere?

• Yes → Company scope (e.g., haircut, consultation, standard exam)
• No → Location scope (e.g., services requiring unique equipment, certifications, or space)

Do I want centralized control?

• Yes → Company scope (franchises, chains)
• No → Location scope (independent operators, franchisees with autonomy)

Will this service expand to other locations?

• Eventually → Start with location scope for pilot, migrate to company scope later
• Never → Location scope (permanent location-specific offering)

Do locations need pricing or configuration flexibility?

• No, standardize → Company scope
• Yes, customize → Location scope (or use company scope with custom fields for metadata)

Migrating Between Scopes

OnSched doesn't directly support changing scope after creation. To migrate:

Location → Company

1. Create a new company-scoped service with the same details
2. Link resources to the new service at all relevant locations
3. Update future appointments to reference the new service
4. Archive the old location-scoped service (showOnline: false or soft-delete)

Company → Location

1. Create new location-scoped services for each location
2. Link resources to the new services
3. Update future appointments to reference the new location-specific service
4. Archive the old company-scoped service

Important: Historical appointments remain linked to the original service. Don't delete services with appointment history.

Mixed Approach

Most businesses use a combination:

Example: Multi-location hair salon

Company-scoped services:

• Haircut (30 min)
• Color Treatment (90 min)
• Blow Dry (20 min)

Location-scoped services:

• Keratin Treatment (120 min, only at flagship location with specialized equipment)
• Kids Cut (20 min, only at family-friendly suburban location)

This gives consistency where it matters while allowing location-specific specialization.

API Interactions

Creating Services

Specify scope when creating:

# Company-scoped
curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Checkup",
    "duration": 30,
    "scope": "COMPANY"
  }'

# Location-scoped
curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Specialized Treatment",
    "duration": 60,
    "scope": "LOCATION",
    "LocationId": "location-uuid"
  }'

Filtering Services

List services with scope awareness:

# All company services (appear everywhere)
curl https://v3.onsched.com/v3/services?scope=COMPANY \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Services available at a specific location (includes company-scoped + location-scoped)
curl https://v3.onsched.com/v3/services?LocationId=LOCATION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Availability Respects Scope

When checking availability:

curl "https://v3.onsched.com/v3/availability?\
startDate=2025-12-01&\
endDate=2025-12-07&\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The system automatically verifies:

• Service is company-scoped, OR
• Service is location-scoped to the requested LocationId

Requesting availability for a service not available at the location returns an error or empty result.

Common Scenarios

Multi-Location Chain with Consistent Services

Use company scope for everything:

• Define services once at company level
• Link resources per location
• Update service definitions centrally
• Customers see the same menu everywhere

Franchise Model with Location Control

Use location scope for everything:

• Each franchise location defines its own services
• Corporate provides guidelines but not enforcement
• Locations customize pricing, duration, offerings
• Customers see only what's available at their chosen location

Hybrid: Core + Specialty Services

Use company scope for core offerings, location scope for specialties:

• Company-scoped: Standard menu everyone offers
• Location-scoped: Unique services based on equipment, staff expertise, or local demand

This balances consistency with flexibility.

Best Practices

Start with Company Scope

If unsure, default to company scope. It's easier to add location-specific services later than to merge location-specific services into a company offering.

Document Scope Decisions

Keep notes on why services are scoped as they are. This helps when:

• Training new staff
• Expanding to new locations
• Evaluating whether to promote location services to company-wide

Use Clear Naming

For location-scoped services, consider including location indicators in the name or description:

• "Downtown VIP Package"
• "Airport Express Service"
• "Suburban Family Special"

This avoids confusion when viewing company-wide service lists.

Limit Location Scope to True Specialties

Don't create location-scoped versions of services just for minor variations. Use:

• Custom fields for metadata differences
• Resource-level configuration for staffing variations
• Company scope for anything that could expand to other locations

Reserve location scope for genuinely unique offerings.

Troubleshooting

Service not appearing at a location

For company-scoped services:

• Verify resources are linked to the service at that location
• Check resource has availability/allocations at the location

For location-scoped services:

• Confirm the service's LocationId matches the requested location
• Ensure service is not soft-deleted

Accidentally created as location-scoped

If you meant to create a company-scoped service:

1. Create a new service with scope: COMPANY
2. Link resources at all locations
3. Archive the incorrectly scoped service

Scope cannot be changed on existing services.

Need different pricing at different locations

Service scope doesn't directly handle pricing variations. Options:

• Use CustomFields to store location-specific pricing metadata
• Create location-scoped versions if prices differ significantly
• Handle pricing logic in your application layer

Related Documentation

• Services Overview – Core service configuration
• Linked Resources – Connecting services to staff/equipment
• Architecture – Understanding the company/location hierarchy
• Resources Overview – Resource configuration
• Availability Guide – How scope affects availability searches

Choose the right scope for each service, and you'll have a flexible system that scales with your business model.