TicketOpus
Sign in Book a demo Get started

Developers

TicketOpus External API

Use the External API to sync catalog, availability, bookings, check-in, pickup logistics, and distribution inventory with reseller, marketplace, mobile, and operations systems.

Base URL https://www.ticketopus.com/api/external/v1

Authentication

API keys are company scoped.

Each company creates API clients in Admin, then grants scopes for the integration. Send the key in X-TicketOpus-Api-Key or as a bearer token.

curl -H "X-TicketOpus-Api-Key: top_xxx" \
  https://www.ticketopus.com/api/external/v1/companies/art-and-craft-studio/items

Scopes

Grant the narrowest access the client needs.

summary:readCompany profile, locations, categories, and users.
availability:readItems, custom fields, rates, availability, crew, and pickup options.
bookings:readBooking list and detailed reservation records.
bookings:writeDry-run validation, booking creation, unified cancellation/rescheduling, and notes.
payments:settleDeclare externally settled funds with provider evidence. This scope does not process a payment.
checkin:readConfigured check-in statuses.
checkin:writeBarcode-based booking or participant check-in.
crew:readStructured crew role directory.
pickup:readLodgings and availability-specific pickup choices.
distribution:readChannel listing feed with allocated capacity.

Reference

External API endpoints

Method Path Scope Purpose
GET/companies/{company}summary:readCompany metadata, branding, capabilities, locations, and categories.
GET/companies/{company}/userssummary:readActive admin users visible to integrations.
GET/companies/{company}/itemsavailability:readBookable items with rates, variants, program rules, and custom fields.
GET/companies/{company}/items/{item}availability:readSingle item by id or URL name.
GET/companies/{company}/items/{item}/custom-fieldsavailability:readCheckout question schema and priced options for one item.
GET/companies/{company}/availabilitiesavailability:readDate-range availability with status, capacity, holds, and price.
GET/companies/{company}/availabilities/{availabilityId}availability:readAvailability detail with rates, crew, fields, and pickup options.
POST/companies/{company}/availabilities/{availabilityId}/bookings/validatebookings:writeDry-run a booking without writing records.
POST/companies/{company}/availabilities/{availabilityId}/bookingsbookings:writeCreate an externally sourced booking with idempotency support.
GET/companies/{company}/bookingsbookings:readSearch booking records by date range and status.
GET/companies/{company}/bookings/{bookingId}bookings:readBooking detail, participants, payments, answers, notes, and attribution.
DELETE/companies/{company}/bookings/{bookingId}bookings:writeCancel a booking after policy evaluation.
GET/companies/{company}/bookings/{bookingId}/cancellation-previewbookings:writePreview refund and cancellation rule outcome.
GET/companies/{company}/bookings/{bookingId}/reschedule-preview?targetAvailabilityId={targetAvailabilityId}bookings:writePreview target capacity, fulfillment, price change, refund, or hosted balance.
POST/companies/{company}/bookings/{bookingId}/reschedulebookings:writeApply a reviewed reschedule with its preview token and an idempotency key.
POST/companies/{company}/bookings/{bookingId}/notesbookings:writeAdd an auditable partner note.
PUT/companies/{company}/checkincheckin:writeCheck in a participant or booking by barcode, ticket, voucher, or external id.
GET/companies/{company}/checkin-statusescheckin:readCompany-specific check-in status choices.
GET/companies/{company}/rolescrew:readCrew role directory for staff scheduling integrations.
GET/companies/{company}/lodgingspickup:readLodging and hotel pickup directory.
GET/companies/{company}/availabilities/{availabilityId}/lodgingspickup:readPickup options allowed for a specific availability.
GET/companies/{company}/distribution-feeddistribution:readReseller feed with channel listings and allocated capacity.

Workflow

Recommended booking flow

1Fetch item schema

Read item rates, variants, and custom fields.

2Search availability

Choose a bookable availability and pickup option.

3Validate

Dry-run quantity, custom answers, voucher, and lodging.

4Create

Post with an idempotency key, customer data, and participants. Declare externally settled funds only with settlement authority and evidence.

5Operate

Use booking detail, notes, check-in, and unified cancellation or reviewed rescheduling after confirmation.

Errors

HTTP status codes

400Validation failed, capacity changed, or booking operation was rejected.
401API key is missing or invalid.
403The key is valid but missing the required scope.
404Company, item, availability, booking, or barcode was not found.
409The preview is stale, another change is active, or the idempotency key belongs to different intent.
429Rate limit exceeded. Retry after the returned Retry-After value.

Example

Create an external booking

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/art-and-craft-studio/availabilities/00000000-0000-0000-0000-000000000000/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": "00000000-0000-0000-0000-000000000000", "value": "yes" }
    ],
    "participants": [
      { "name": "Avery Morgan", "customerTypeName": "Adult" },
      { "name": "Riley Morgan", "customerTypeName": "Adult" }
    ]
  }'

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/art-and-craft-studio/bookings/00000000-0000-0000-0000-000000000000/reschedule \
  -d '{
    "targetAvailabilityId": "00000000-0000-0000-0000-000000000001",
    "expectedPreviewToken": "reviewed-preview-token",
    "actorName": "Reseller support",
    "reason": "Guest requested a later session"
  }'