TicketOpus External API

curl -H "X-TicketOpus-Api-Key: top_xxx" \
  https://www.ticketopus.com/api/external/v1/companies/your-company/items

Scopes

Grant the narrowest access the client needs.

Reference

External API endpoints

Workflow

Recommended booking flow

Errors

HTTP status codes

Example

Create an external booking

In these samples, replace your-company with your company's URL name and the uppercase placeholders, such as AVAILABILITY_ID, with real IDs from the API.

This example records funds already settled by a trusted external partner. The API client needs bookings:write and payments:settle; the settlement provider and reference are required when amountPaid is greater than zero.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-TicketOpus-Api-Key: top_xxx" \
  https://www.ticketopus.com/api/external/v1/companies/your-company/availabilities/AVAILABILITY_ID/bookings \
  -d '{
    "customerName": "Avery Morgan",
    "customerEmail": "[email protected]",
    "requestedQuantity": 2,
    "idempotencyKey": "reseller-order-8437",
    "voucherNumber": "FH-12345",
    "externalId": "reseller-booking-8437",
    "amountPaid": 90.00,
    "settlementProvider": "reseller-ledger",
    "settlementReference": "settlement-8437",
    "customFieldAnswers": [
      { "customFieldId": "CUSTOM_FIELD_ID", "value": "yes" }
    ],
    "participants": [
      { "name": "Avery Morgan", "customerTypeName": "Adult" },
      { "name": "Riley Morgan", "customerTypeName": "Adult" }
    ]
  }'

Bookings are priced as the company's own booking page prices them: session prices, price rules, mandatory fees, priced options and tax. Add "promoCode" to apply one of the company's promo codes; the same dates and redemption limit apply. Add "packageId" to choose one of the activity's packages. The validate call takes both fields and returns estimatedDiscount with the other estimates. Camps and class series sold as enrollments in a series of sessions are booked on the company's site, not through the API.

Review and apply a reschedule

First request a preview for the target time. Submit its previewToken as expectedPreviewToken; if booking, inventory, fulfillment, pricing, or payment state changes, the commit returns 409 and requires a fresh preview.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-TicketOpus-Api-Key: top_xxx" \
  -H "Idempotency-Key: reseller-reschedule-8437" \
  https://www.ticketopus.com/api/external/v1/companies/your-company/bookings/BOOKING_ID/reschedule \
  -d '{
    "targetAvailabilityId": "TARGET_AVAILABILITY_ID",
    "expectedPreviewToken": "reviewed-preview-token",
    "actorName": "Reseller support",
    "reason": "Guest requested a later session"
  }'

Other interfaces

SCIM directory sync and the public activity feed

Your identity provider can keep the company's staff directory in step through SCIM 2.0 at https://www.ticketopus.com/api/your-company/scim/v2. Use an API client key granted the scim scope. Deprovisioning a user ends that person's team access to the company, except an Owner's. SCIM does not create sign-in accounts or restore access, groups are read-only, and filters support eq only.

Each company also publishes its bookable activities without a key, as Schema.org data at /api/v1/companies/your-company/discovery/schema-org or the same feed at /api/v1/companies/your-company/feed/activities.json. Only active activities that are publicly bookable online are listed.