Zoho Creator API

Source: Backup ticket-booking/ — config/zoho-v3.php, services/ZohoService.php, test-zoho.php Tested: 2026-05-12 via curl against live houseoflegends-booking app

Why This Matters

Zoho Creator is our system of record for inventory, bundles, and bookings. Before any booking is confirmed, we check live availability in Zoho to ensure accurate seat counts. After payment, we sync the booking back to Zoho so the team can manage reservations through their existing tools. Hamza’s perspective: Your existing Zoho system tracks what’s available and what you’ve sold. The new HOL system talks to Zoho to get real-time inventory, then writes bookings back after payment. This keeps both systems in sync without disrupting your current workflow.

This integration is one-way sync from Zoho for reads. Write operations (booking creation, inventory updates) happen within HOL’s Convex backend, which then syncs back to Zoho.

How It Works

Reading Live Inventory (for guests booking)

Guest selects a show and date on the booking page
HOL backend calls Zoho Creator’s ShowInventoryV4_Report to get live seat availability
Zoho returns available counts by zone and price tier
Guest sees accurate, real-time availability

Creating a Booking (after payment)

Guest completes payment on OnePay
HOL backend creates the reservation in Convex
HOL backend calls Zoho Creator’s Booking form to create a booking record
HOL backend calls Zoho to update sold count in ShowInventoryV4_Report
Both systems stay in sync

What We Tested

All API calls used the OAuth2 refresh token flow:

POST https://accounts.zoho.com/oauth/v2/token
  grant_type=refresh_token
  client_id=<ZOHO_CLIENT_ID>
  client_secret=<ZOHO_CLIENT_SECRET>
  refresh_token=<ZOHO_REFRESH_TOKEN>

Base URL: https://creator.zoho.com/api/v2/thehouseoflegends/houseoflegends-booking

Token Scopes

ZohoCreator.form.CREATE
ZohoCreator.form.UPDATE
ZohoCreator.report.READ
ZohoCreator.report.UPDATE

Key Concepts

Report vs Form Endpoints

Type	Endpoint Pattern	Purpose
Report	`/report/<ReportName>`	Read-only data retrieval
Form	`/form/<FormName>`	Create and update operations

Record IDs

Zoho uses compound IDs like 4910610000000220005 to identify records. These IDs are used in update operations via criteria filters.

Delete operations are not available with current token scopes. Use status updates (e.g., marking as “Failed”) instead of deleting records.

Endpoints Tested

Read — ShowInventoryV4_Report

GET /report/ShowInventoryV4_Report?from=0&limit=5

Returns inventory rows for shows:

{
  "show_name": "Test",
  "show_date": "16-May-2026",
  "zone": "Standard",
  "price": "650000.00",
  "capacity": "18",
  "sold": "4",
  "held": "0",
  "available": "14",
  "ID": "4910610000000220005"
}

Works. Returns live inventory with date, zone, price, capacity, sold/held/available counts.

Read — BundleCatalog_Report

GET /report/BundleCatalog_Report?from=0&limit=10

Returns bundle catalog:

{
  "bundle_id": "BDL-01",
  "bundle_name": "Show Ticket",
  "price_standard": "550000.00",
  "price_best": "750000.00",
  "category": "BDL",
  "is_active": "true"
}

Works. Bundles have price_standard, price_best, price_chill per-zone pricing.

Read — ShowCatalog_Report

GET /report/ShowCatalog_Report?from=0&limit=5

Returns show metadata:

{
  "show_name": "Sunday Salon",
  "subtitle": "Live jazz. Every Sunday. Your perfect evening.",
  "description": "...",
  "Directors": "House of Legends",
  "Time": "3 hours",
  "Is_Active": "Active",
  "Image": "/api/v2/thehouseoflegends/houseoflegends-booking/report/ShowCatalog_Report/.../Image/download?filepath=..."
}

Works. Show landing pages can source title, description, image, director, time from this.

Read — All_Bookings

GET /report/All_Bookings?from=0&limit=5

Returns booking records:

{
  "ID": "4910610000000232003",
  "customer_name": {
    "first_name": "Margarita",
    "last_name": "Zhukova"
  },
  "customer_email": "zhukova.margarita22@gmail.com",
  "customer_phone": "0944771968",
  "show_date": "16-May-2026",
  "zone": "Standard",
  "bundle_pax": "4",
  "payment_status": "Paid",
  "payment_method": "OnePay",
  "payment_date": "11-May-2026 13:33:01",
  "vpc_TransactionNo": "PAY-ZXvjcrfjT3aoKdmTJkOsDA",
  "vpc_TxnResponseCode": "0"
}

Works. Full booking records with customer info, payment details.

Create — Booking form

POST /form/Booking

Payload:

{
  "data": {
    "show_date": "16-May-2026",
    "zone": "Standard",
    "bundle": "4910610000000184003",
    "bundle_pax": 2,
    "bundle_price": 1100000,
    "customer_name": {
      "first_name": "Test",
      "last_name": "Customer"
    },
    "customer_email": "test@example.com",
    "customer_phone": "0900000000",
    "inventory_id": "4910610000000220005",
    "day_group": "Thu-Sun",
    "available_label": "Available: 18 seats"
  }
}

Result: {"code":3000,"data":{"ID":"4910610000000233003"},"message":"Data Added Successfully"} Works. Booking created with ID returned. Note: On-Success workflow scripts may trigger (the test showed a script warning but data was saved).

Update — Inventory (sold/held)

PATCH /report/ShowInventoryV4_Report

Payload:

{
  "criteria": "ID==4910610000000220005",
  "data": {
    "sold": 6
  }
}

Result: {"code":3000,"data":{"ID":"4910610000000220005"},"message":"Data Updated Successfully"} Works. Inventory sold count updated. Verified sold went from 4 → 6.

Limitations

Cannot Delete Records

DELETE /report/All_Bookings/ID

Returns:

{"code":2945,"description":"This is an invalid oauthscope. Please regenerate the oauthtoken corresponding to the API with proper oauthscope."}

No delete permission. Token scope only allows create/update on forms and reports. Use status updates (e.g., marking as payment_status: "Failed") instead.

Wrong Scope for CRM and Books

Zoho CRM API — Returns OAUTH_SCOPE_MISMATCH. Token only has Creator scopes (ZohoCreator.form.CREATE, ZohoCreator.report.READ, etc.). No CRM scope. Zoho Books API — Returns You are not authorized to perform this operation. Token has no Books scope. CRM and Books require separate OAuth scopes.

Technical Details

Zoho Credentials

Credentials are stored in:

apps/frontend/raw/ticket-booking/.env (backup, read-only)
Convex env vars (set via npx convex env set)

Token scopes: ZohoCreator.form.CREATE ZohoCreator.form.UPDATE ZohoCreator.report.READ ZohoCreator.report.UPDATE

Report/Form Reference

Report/Form	Link Name	Fields
ShowInventoryV4_Report	`ShowInventoryBeta`	show_date, zone, price, capacity, held, sold, available, show_time, singer
BundleCatalog_Report	`BundleCatalog`	bundle_id, bundle_name, category, price_standard, price_best, price_chill, pax, is_active, applicable_days
All_Bookings	`Booking`	customer_name, customer_email, customer_phone, show_date, zone, bundle_pax, bundle_price, payment_status, payment_method, inventory_id, day_group
ShowCatalog_Report	`ShowCatalog`	show_name, subtitle, description, directors, actors, scriptwriter, time, image, is_active

Conclusion

Creator token is sufficient for:

Reading live inventory (availability, pricing)
Reading bundle catalog
Reading show catalog (for landing pages)
Creating booking records after payment
Updating sold/held counts after payment

Creator token cannot do:

Delete bookings (only mark as Failed)
CRM contact/deal sync (wrong scope)
Invoice generation (wrong scope)

To use CRM/Books, Hamza needs to add those scopes in Zoho API Console and re-authorize the OAuth app.

Payments

OnePay payment integration

Notifications

Email and WhatsApp notifications

Booking Experience

Booking flow integration

Event Management

Event scheduling

Foundation

Guest-Facing

Operations

Inquiry

Integrations

Admin

Zoho Creator API

Zoho Creator API

Why This Matters

How It Works

Reading Live Inventory (for guests booking)

Creating a Booking (after payment)

What We Tested

Token Scopes

Key Concepts

Report vs Form Endpoints

Record IDs

Endpoints Tested

Read — ShowInventoryV4_Report

Read — BundleCatalog_Report

Read — ShowCatalog_Report

Read — All_Bookings

Create — Booking form

Update — Inventory (sold/held)

Limitations

Cannot Delete Records

Wrong Scope for CRM and Books

Technical Details

Conclusion

See Also

Payments

Notifications

Booking Experience

Event Management

Foundation

Guest-Facing

Operations

Inquiry

Integrations

Admin

​Zoho Creator API

​Why This Matters

​How It Works

​Reading Live Inventory (for guests booking)

​Creating a Booking (after payment)

​What We Tested

​Token Scopes

​Key Concepts

​Report vs Form Endpoints

​Record IDs

​Endpoints Tested

​Read — ShowInventoryV4_Report

​Read — BundleCatalog_Report

​Read — ShowCatalog_Report

​Read — All_Bookings

​Create — Booking form

​Update — Inventory (sold/held)

​Limitations

​Cannot Delete Records

​Wrong Scope for CRM and Books

​Technical Details

​Conclusion

​See Also

Payments

Notifications

Booking Experience

Event Management

Zoho Creator API

Why This Matters

How It Works

Reading Live Inventory (for guests booking)

Creating a Booking (after payment)

What We Tested

Token Scopes

Key Concepts

Report vs Form Endpoints

Record IDs

Endpoints Tested

Read — ShowInventoryV4_Report

Read — BundleCatalog_Report

Read — ShowCatalog_Report

Read — All_Bookings

Create — Booking form

Update — Inventory (sold/held)

Limitations

Cannot Delete Records

Wrong Scope for CRM and Books

Technical Details

Conclusion

See Also