Skip to main content

​
Overview

The Public Merchant API provides unauthenticated endpoints that power the customer-facing booking interface (Tango app). These endpoints allow customers to discover merchants, browse services, check availability, and gather information needed for making bookings.
These endpoints are accessed via the /api/v1/merchants/{merchantName} base path and do not require authentication.

​
Base Path

GET /api/v1/merchants/{merchantName}
The {merchantName} path parameter is the merchant’s URL-friendly name (e.g., “joes-barber-shop”).

​
Endpoints

​
Get Merchant Information

Retrieve comprehensive information about a merchant including location, services, and business hours. 
curl https://api.reservations.com/api/v1/merchants/joes-barber-shop

​
Response

​
merchant_name
string
Display name of the merchant
​
url_name
string
URL-friendly merchant identifier
​
contact_email
string
Primary contact email
​
introduction
string
Short introduction text
​
announcement
string
Current announcement or notice
​
about_us
string
Detailed about us information
​
parking_info
string
Parking instructions
​
payment_info
string
Payment methods and policies
​
timezone
string
Merchant’s timezone (e.g., “America/New_York”)
​
location_id
integer
Primary location ID
​
country
string
Country name
​
city
string
City name
​
postal_code
string
Postal/ZIP code
​
address
string
Street address
​
formatted_location
string
Full formatted address string
​
geo_point
object
Geographic coordinates
​
services
array
Services grouped by category
​
business_hours
object
Business hours by day of week (0=Sunday, 6=Saturday)

​
Get Service Details

Get detailed information about a specific service including phases and pricing. 
GET /api/v1/merchants/{merchantName}/locations/{locationId}/services/{serviceId}

curl https://api.reservations.com/api/v1/merchants/joes-barber-shop/locations/1/services/5

​
Path Parameters

​
merchantName
string
required
URL-friendly merchant identifier
​
locationId
integer
required
Location ID
​
serviceId
integer
required
Service ID

​
Response

​
id
integer
Service ID
​
name
string
Service name
​
description
string
Service description
​
total_duration
integer
Total duration in minutes
​
price
object
Formatted price information
​
price_type
string
Price type: “fixed”, “variable”, or “per_person”
​
formatted_location
string
Service location address
​
geo_point
object
Geographic coordinates
​
phases
array
Service phases (for multi-phase services)

​
Get Booking Summary

Get a summary of service information for the booking confirmation screen. 
GET /api/v1/merchants/{merchantName}/locations/{locationId}/services/{serviceId}/summary

curl https://api.reservations.com/api/v1/merchants/joes-barber-shop/locations/1/services/5/summary

​
Response

​
name
string
Service name
​
total_duration
integer
Duration in minutes
​
price
object
Formatted price
​
price_type
string
Pricing model
​
formatted_location
string
Location address

​
Check Service Availability

Get available time slots for a service within a date range. 
GET /api/v1/merchants/{merchantName}/locations/{locationId}/services/{serviceId}/availability?start={startDate}&end={endDate}

curl "https://api.reservations.com/api/v1/merchants/joes-barber-shop/locations/1/services/5/availability?start=2024-03-01T00:00:00Z&end=2024-03-07T23:59:59Z"

​
Query Parameters

​
start
string
required
Start date in RFC3339 format (ISO 8601)
​
end
string
required
End date in RFC3339 format (ISO 8601)

​
Response

Returns an array of availability by date:
​
date
string
Date in ISO format
​
is_available
boolean
Whether any slots are available on this date
​
morning
string[]
Array of available morning time slots
​
afternoon
string[]
Array of available afternoon time slots

​
Get Next Available Slot

Find the next available booking slot for a service. 
GET /api/v1/merchants/{merchantName}/locations/{locationId}/services/{serviceId}/availability/next

curl https://api.reservations.com/api/v1/merchants/joes-barber-shop/locations/1/services/5/availability/next

​
Response

​
date
string
Next available date
​
time
string
Next available time slot

​
Get Disabled Days

Get days when the service is unavailable for booking. 
GET /api/v1/merchants/{merchantName}/locations/{locationId}/services/{serviceId}/availability/disabled-days

curl https://api.reservations.com/api/v1/merchants/joes-barber-shop/locations/1/services/5/availability/disabled-days

​
Response

​
closed_days
integer[]
Array of day numbers when closed (0=Sunday, 6=Saturday)
​
min_date
string
Earliest bookable date
​
max_date
string
Latest bookable date

​
Use Cases

​
Customer Booking Flow

  1. Discovery: Get merchant information to display location and services
  2. Service Selection: Show service details when customer selects a service
  3. Date Selection: Use disabled days to configure the date picker
  4. Time Selection: Fetch availability for the selected date range
  5. Confirmation: Display booking summary before creating the booking

​
Integration Example

// Step 1: Load merchant information
const merchantInfo = await fetch('/api/v1/merchants/joes-barber-shop').then(r => r.json());

// Step 2: Get service details
const service = await fetch(
  `/api/v1/merchants/joes-barber-shop/locations/${merchantInfo.location_id}/services/5`
).then(r => r.json());

// Step 3: Check disabled days for calendar
const disabledDays = await fetch(
  `/api/v1/merchants/joes-barber-shop/locations/${merchantInfo.location_id}/services/5/availability/disabled-days`
).then(r => r.json());

// Step 4: Get availability for selected week
const start = new Date('2024-03-01').toISOString();
const end = new Date('2024-03-07').toISOString();

const availability = await fetch(
  `/api/v1/merchants/joes-barber-shop/locations/${merchantInfo.location_id}/services/5/availability?start=${start}&end=${end}`
).then(r => r.json());

// Step 5: Display booking summary
const summary = await fetch(
  `/api/v1/merchants/joes-barber-shop/locations/${merchantInfo.location_id}/services/5/summary`
).then(r => r.json());

​
Best Practices

  • Cache merchant information: Merchant info changes infrequently, cache it to reduce API calls
  • Batch availability checks: Fetch availability for entire weeks rather than individual days
  • Handle timezones: Always use the merchant’s timezone from the merchant info response
  • Error handling: Handle cases where merchants or services don’t exist gracefully
  • Respect disabled days: Use the disabled-days endpoint to prevent users from selecting unavailable dates

Build docs developers (and LLMs) love

Get started for freeTalk to us