Services Overview

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

What Are Services?

Services define what customers can book. They represent offerings like:

Appointments – Consultations, checkups, coaching sessions
Classes – Fitness classes, workshops, training sessions
Rentals – Equipment, rooms, vehicles
Experiences – Tours, events, activities

Each service specifies its duration, how slots are generated, which resources can deliver it, and booking constraints.

Core Properties

Name and Description

name (required) – Display name shown to customers ("Haircut", "Strategy Session")
description (optional) – Additional details, instructions, or requirements

Keep names concise and descriptions clear. These appear in booking interfaces.

Duration

duration (required) – Service length in minutes

Duration determines how long appointments last and affects availability calculations. For example, a 30-minute service can fit two slots per hour (assuming no padding or interval constraints).

Duration Selection

Allow customers to choose appointment length:

durationSelect (boolean) – Enable variable duration (default: false)
durationMin – Minimum selectable duration
durationMax – Maximum selectable duration
durationInterval – Step increment (e.g., 15-minute intervals)

Example:

A consulting service allows 30, 45, or 60-minute sessions:

{
  "duration": 30,
  "durationSelect": true,
  "durationMin": 30,
  "durationMax": 60,
  "durationInterval": 15
}

Customers can select 30, 45, or 60 minutes. Use overrideDuration when requesting availability or creating appointments to specify the chosen length.

Padding

padding (integer) – Buffer time added after each appointment (in minutes, default: 0)

Padding creates downtime between bookings for:

Cleanup or prep work
Travel between locations
Admin tasks
Avoiding back-to-back fatigue

Example:

A 30-minute haircut with 10 minutes of padding:

Appointment occupies 9:00 - 9:30
Padding blocks 9:30 - 9:40
Next appointment can start at 9:40

Padding is invisible to customers but prevents overbooking resources.

Scheduling Rules

Booking Interval

bookingInterval (integer) – How often time slots are offered (in minutes, default: 0)

When 0, slots start every duration minutes (or every interval minutes if specified in availability request). Setting a booking interval spaces out start times differently than duration.

Example:

A 30-minute massage with bookingInterval: 60 offers slots at:

9:00 (next available: 10:00, not 9:30)
10:00
11:00

Useful for services that need longer breaks between clients than the service duration.

Show Online

showOnline (boolean) – Whether service appears in public booking interfaces (default: true)

Set to false to hide internal or administrative services while keeping them bookable via API.

Visibility

Services are visible when:

showOnline: true
Not soft-deleted (deletedAt is null)
Associated with active resources at the location

Advanced Settings

All-Day Booking

allDayBooking (boolean) – Treat as full-day event (default: false)

When true, the service occupies the entire day regardless of duration. Useful for:

Day-long workshops
Equipment rentals (checkout/return same day)
Full-day experiences

Payment Requirements

requiresPayment (boolean) – Appointment requires payment processing (default: false)
authorizeOnly (boolean) – Authorize card without capturing (default: false)
feeAmount (decimal) – Service fee
feeTaxable (boolean) – Whether fee is subject to tax

Payment settings signal intent but don't directly process payments. Integrate with your payment processor and use these flags to determine when to charge customers.

Cancellation Policy

nonRefundable (boolean) – Service cannot be refunded (default: false)
cancellationFeeAmount (decimal) – Fee charged for cancellations
cancellationFeeTaxable (boolean) – Whether cancellation fee is taxable

Use these to communicate policy; enforcement happens in your business logic or payment integration.

Sort Order

sortKey (integer) – Display order in lists (default: 0)

Lower values appear first. Use to prioritize popular services or organize by category.

Image

imageUrl (string) – URL to service image for display in booking interfaces

Show service photos, icons, or branding to help customers identify offerings.

Creating a Service

Basic Service Example

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dental Cleaning",
    "description": "Routine teeth cleaning and exam",
    "duration": 30,
    "padding": 10,
    "scope": "COMPANY",
    "showOnline": true
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Dental Cleaning",
  "description": "Routine teeth cleaning and exam",
  "duration": 30,
  "padding": 10,
  "scope": "COMPANY",
  "showOnline": true,
  "createdAt": "2025-11-25T10:00:00Z"
}

Service with Variable Duration

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consulting Session",
    "duration": 60,
    "durationSelect": true,
    "durationMin": 30,
    "durationMax": 120,
    "durationInterval": 30,
    "scope": "COMPANY"
  }'

Customers can book 30, 60, 90, or 120-minute sessions.

Updating Services

Use PUT /v3/service/:id to modify existing services:

curl -X PUT https://v3.onsched.com/v3/service/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "padding": 15,
    "description": "Routine cleaning with fluoride treatment"
  }'

Important: Changing duration or padding affects existing future appointments if your system recalculates slots. Most implementations apply changes only to new bookings.

Listing Services

Retrieve available services:

# All company services
curl https://v3.onsched.com/v3/services?limit=50 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by location (if location-scoped)
curl https://v3.onsched.com/v3/services?LocationId=LOCATION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes pagination:

{
  "data": [
    {
      "id": "service-1",
      "name": "Haircut",
      "duration": 30
    },
    {
      "id": "service-2",
      "name": "Color Treatment",
      "duration": 90
    }
  ],
  "count": 2,
  "limit": 50,
  "page": 1
}

Deleting Services

Services use soft-delete (they're archived, not removed):

curl -X DELETE https://v3.onsched.com/v3/service/SERVICE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Deleted services:

No longer appear in availability searches
Remain linked to historical appointments
Can be restored if needed

Best practice: Instead of deleting, set showOnline: false to hide services while preserving full history.

Custom Fields

Extend services with custom data:

CustomFields (object) – Key-value pairs for additional attributes

Example:

{
  "name": "Premium Massage",
  "duration": 60,
  "CustomFields": {
    "category": "wellness",
    "difficulty": "intermediate",
    "memberOnly": "true"
  }
}

Use custom fields to:

Categorize services for filtering
Store integration-specific metadata
Track internal identifiers

Custom fields are indexed and searchable but not validated—ensure your application handles them correctly.

Relationship with Other Entities

Services ↔ Resources

Services link to resources (staff, equipment) that can fulfill them. See:

Services ↔ Locations

Service scope determines location visibility:

Company-scoped services – Available at all locations
Location-scoped services – Restricted to specific location

See Service Scoping.

Services ↔ Appointments

Appointments reference services to inherit:

Duration (or overrideDuration)
Padding rules
Booking limits
Eligible resources

See Appointment Guide.

Common Use Cases

Service Bundles

OnSched doesn't directly support "package" bookings, but you can:

Create a parent service representing the bundle (e.g., "Spa Package")
Use longer duration to cover all treatments
Store bundle details in CustomFields
Handle sub-appointment logic in your application

Recurring Services

For services that repeat (weekly classes, subscriptions):

Use the recurring appointments feature (if available)
Or create individual appointments programmatically using your scheduling logic
Store recurrence metadata in CustomFields

Group Services

For classes or group bookings, use bookingsPerSlot to allow multiple customers in one time slot. See Max Capacity.

Mobile Services

For services delivered at customer locations:

Configure service normally
Store customer address in appointment notes or custom fields
Use resource schedules to account for travel time

Best Practices

Naming Conventions

Keep names short and recognizable
Use descriptions for details, instructions, or requirements
Avoid jargon unless your audience expects it

Duration and Padding

Set realistic durations – Include time for actual service delivery
Use padding for transitions – Cleanup, setup, travel, breaks
Test availability – Ensure slots appear as expected before going live

Avoid Over-Configuration

Start simple:

Basic duration and padding
Add variable duration later if customers request it
Enable booking limits only when necessary

Complexity makes troubleshooting harder. Add features as needs emerge.

Service Versioning

When significantly changing a service (price, duration, structure):

Create a new service with an updated name
Set old service to showOnline: false
Existing appointments remain linked to old version
New bookings use new version

This preserves historical accuracy.

Troubleshooting

Service not appearing in availability

Check:

Service has duration set (required)
Service is linked to at least one resource at the location
Resource has operating hours/allocations defined
Service isn't soft-deleted
Location is active

Duration selection not working

Ensure:

durationSelect is true
durationMin, durationMax, and durationInterval are set
overrideDuration value is a multiple of durationInterval
Override is within min/max range

Padding not blocking availability

Padding is added automatically during availability calculations and appointment creation. You don't need to manually create padding blocks—the system handles it.

What Are Services?

Core Properties

Name and Description

Duration

Duration Selection

Padding

Scheduling Rules

Booking Interval

Show Online

Visibility

Advanced Settings

All-Day Booking

Payment Requirements

Cancellation Policy

Sort Order

Image

Creating a Service

Basic Service Example

Service with Variable Duration

Updating Services

Listing Services

Deleting Services

Custom Fields

Relationship with Other Entities

Services ↔ Resources

Services ↔ Locations

Services ↔ Appointments

Common Use Cases

Service Bundles

Recurring Services

Group Services

Mobile Services

Best Practices

Naming Conventions

Duration and Padding

Avoid Over-Configuration

Service Versioning

Troubleshooting

Service not appearing in availability

Duration selection not working

Padding not blocking availability

Related Documentation