Skip to main content

Alvera Service Commerce Platform (SCP) API

Alvera SCP is a vertical operating system for service-based businesses. This documentation covers how to integrate with the SCP API using the TypeScript SDK.

How to Use These Docs​

PagePurpose
OverviewPlatform architecture, user personas, and API reference by tag group
Setting Up SCP ClientDetailed Docker setup and SDK configuration
API ReferenceInteractive OpenAPI documentation with "Try it" functionality
CookbookStep-by-step guides for common tasks

Cookbook​

Interactive guides for building with the SCP API:

Getting Started​

Service Manager​

More cookbooks coming soon: Booking Flow, Customer Management, Payment Processing

What You Can Build​

VerticalExamples
Beauty & WellnessSalons, medspas, barbershops, nail studios
HealthcareMedical practices, dental offices, therapy clinics
FitnessGyms, yoga studios, personal trainers
Professional ServicesConsultants, tutors, coaches, photographers
Home ServicesCleaning, repairs, pet grooming

Platform Architecture​

Alvera SCP is designed as a white-label multi-tenant service commerce platform where:

  • Tenant - Platform operator (your company)
  • MerchantOrg - B2B holding companies that own one or more businesses
  • Merchant - Individual businesses serving end customers
  • EndCustomer - Consumers who book appointments
Tenant (Platform Operator)
  ├─> Users (platform staff with role-based permissions)
  ├─> Plugins (payment processors, SMS, email, integrations)
  └─> MerchantOrgs (B2B holding companies)
       └─> Merchants (individual businesses)
            ├─> Providers (service providers who deliver services)
            ├─> Locations (physical locations)
            ├─> Services (what they offer)
            └─> EndCustomers (consumers)
                 └─> Bookings (parent container)
                      ├─> Appointments (child calendar slots)
                      ├─> Invoices (billing)
                      └─> Notifications (reminders, confirmations)

User Personas​

1. EndCustomer​

Consumers who book and pay for services.

API Capabilities:

  • Browse services and available time slots
  • Book appointments
  • Manage appointments across multiple merchants
  • Store payment methods on file
  • Check in via QR code
  • Pay and tip at checkout
  • View appointment history and invoices

2. Merchant Staff​

Employees managing daily business operations.

API Capabilities:

  • Customer management and lead tracking
  • Appointment scheduling and calendar
  • Waitlist management
  • Direct and group messaging
  • Process payments, refunds, chargebacks
  • Manage locations, services, provider schedules

3. Platform Staff (Tenant Users)​

Platform operators managing the entire system.

API Capabilities:

  • Onboard and manage merchant organizations/merchants
  • User and role management
  • Subscription and billing management
  • Access audit logs across all merchants

4. AI Agents​

Autonomous systems that interact with the platform programmatically via API.

API Capabilities:

  • Authenticate via API tokens
  • Book appointments on behalf of end customers
  • Query availability and services
  • Retrieve customer information and history
  • Send notifications and messages
  • Process payments and refunds
  • Access audit trails for AI actions

Booking Flow​

The complete booking and payment flow: Discovery → Booking → Deposit → Service → Balance → Tip

Key Concept: A Booking is the parent container (the "cart" or "order") that holds:

  • Multiple Appointments (calendar slots with providers)
  • Invoices (billing documents)
  • Payment Contracts (recurring payment rules)
  • Notifications (reminders, confirmations)

Quick Start​

  1. Initialize Client - Connect and authenticate with the API
  2. Setting Up SCP Client - Detailed SDK setup with Docker
  3. API Reference - Interactive API documentation with "Try it" functionality

API Reference by Tag Group​

Authentication & Authorization​

ServiceDescriptionAPI
AuthenticationSign in to obtain Bearer tokens for API access→
UserPlatform user management and permissions→
RoleRole-based access control configuration→

Platform Operations​

ServiceDescriptionAPI
TenantMulti-tenant platform management→
MerchantOrgB2B holding company management→

Platform Finance​

ServiceDescriptionAPI
SubscriptionPlatform subscription management→
TransactionFinancial transaction processing→
TransactionJournalTransaction audit and reconciliation→

Merchant Operations​

ServiceDescriptionAPI
MerchantIndividual business location management→
LocationPhysical location configuration→
ProviderService provider (staff) management→
ServiceService catalog and pricing→
ServiceCategoryService category organization→
ServicePackageBundle and package configuration→
AvailabilityProvider and location availability→
BookingBooking container (cart/order) management→
BookingEnquiryBooking inquiry and waitlist→
BookingPolicyBooking rules and policies→
AppointmentIndividual appointment slots→
AppointmentSearchAppointment search and filtering→

Merchant Finance​

ServiceDescriptionAPI
InvoiceInvoice generation and management→
PaymentAccountStored payment methods→
PaymentContractRecurring payment rules→
PaymentPolicyPayment terms and policies→

Customer Operations​

ServiceDescriptionAPI
EndCustomerCustomer profile management→
EndCustomerSearchCustomer search and filtering→
MessageDirect and group messaging→
NotificationPolicyReminder and notification configuration→
FormResponseForm and intake submissions→

Compliance & Branding​

ServiceDescriptionAPI
AuditLogSecurity and compliance audit trail→
WebsiteBooking page customization→

Development & Testing​

ServiceDescriptionAPI
SandboxDevelopment utilities and data reset→

View Full API Reference →

Downloads​

Quality Checks & Integration Tests​

Running Integration Tests​

The SCP platform includes a comprehensive Vitest test suite that validates all API endpoints:

# Setup and run tests
cd integration-tests
npm install
npm test

Test Coverage​

Integration tests cover:

  • Authentication - Login, token refresh, session management
  • CRUD Operations - Create, read, update, delete for all resources
  • Business Logic - Booking flows, availability checks, payment processing
  • Error Handling - Validation errors, authorization failures, edge cases

Environment Variables​

# Required for running tests
ADMIN_EMAIL=admin@alvera-scp-dev.local
ADMIN_PASSWORD=DevPassword123!
TENANT_NAME=alvera-scp-dev

API Coverage Report​

After running tests, view the API coverage report:

npm run test:coverage

This shows which endpoints are tested and identifies gaps in test coverage.