Developer portal

Frequently asked questions

General Questions

How do I get API access?
To receive an API key, please send a request to [email protected].
What are the request limits?
At this time, we are not applying any standard request limits. That said, if suspicious, abusive, or unusually high-volume activity is detected or reported, we may introduce appropriate request limits to protect the stability, security, and fair use of the service.
Is the API transactional?
Yes, the API is transactional.
Is there a separate API instance for testing purposes?
For testing, you can use the sandbox environment via https://api-sandbox.londontheatredirect.com/rest/v2. Learn more about the sandbox environment in the documentation.
Can I make test bookings on the real API?
No. Use the available testing options instead.
Can I add our company branding to confirmation emails sent to customers?
Emails can be customised upon request.
What is the default commission structure?
This depends on your business size and sales volume. Contact [email protected] for details.
Can I receive net rates through the API to set my own margin?
Yes, both net and commissionable rates are available via the API.
Why does the 'Your basket is currently locked' error appear?

This error has two distinct causes:

  • Payment in progress: the basket enters a locked 'payment state' when a customer has a payment in progress. If they simultaneously try to add another ticket to the same basket, the system rejects the action to protect payment integrity.
  • This message may show up when BoxOffice is unavailable.
Why does the error "One or more tickets belong to non-bookable performance" appear?
This occurs with events that have related performances, for example Harry Potter. The message appears when a customer attempts to book a second performance only. Related performances cannot be booked independently. They are added automatically after the master performance is added into the basket.
On Sandbox/Staging, why does the seat selection price differ from the basket price?
The staging environment uses non-live data for the seating plan, but the checkout process connects to live data. This mismatch is expected and is specific to staging. It does not occur in production.
Some seats appear available on the website but are unavailable via API. Why?
Loading the seating map triggers an availability polling cycle. During a single session, several polling calls are made, and every nth call triggers a synchronization with live data. Crucially, the first load is cached - a refresh with live data follows shortly thereafter. This means there can be a brief window where the website shows stale availability that the API has already updated.
Can prices on the seating plan differ from prices in the basket? Which is the final price?
Yes, a discrepancy is possible. Seating plan prices are cached and may be slightly out of date. The price shown in the basket at checkout is always the current, accurate price and should be treated as final.
How is the refund protection plan handled, and who manages payment processing?

The answer depends on which integration path is used:

  • TTX API (direct): customers will not have access to the refund protection add-on.
  • TTX payment gateway: refunds are managed by the external company. Payment processing, including absorption of card fees, is handled entirely by TTX.
  • Own payment gateway (Optimizer): payment processing is managed by the partner.
Why is the OfferPrice value higher than CurrentPrice in the API response?
The OfferPrice can be higher than the CurrentPrice in some scenarios. This is expected behavior. CurrentPrice is the minimum price available for the current event and partner, already accounting for any active offers. OfferPrice is the minimum price within the offered/promotional price tier specifically, but not necessarily the lowest price in general. Because CurrentPrice reflects all discounts already applied, it will often be lower than OfferPrice.
Can General Admission (Best Seats) tickets and reserved (Allocation) seats be added to one basket?
Yes, but reserved tickets and GA tickets must be called separately.
Ticket basket expiry: why does the converted local expiry time show around 60-70 minutes, but the basket clears after only 10-20 minutes?
The expiry time must be kept in the UK time zone instead of the local one.

Webhooks

Does the webhook get triggered when barcodes are generated or updated?

Barcode webhook: fired only when barcodes are generated, not when they are updated afterwards.

Transaction changed webhook: fired on booking creation, cancellation, and manual updates made by support or system actions.

Why might no webhook arrive after a booking is made?

Common causes:

  • Barcodes have not been generated yet - a delay is expected and normal.
  • Expectation mismatch - booking updates do not trigger a webhook; only the events listed above do.
  • The webhook endpoint is not reachable or is misconfigured.
  • Signature validation is rejecting the payload on the receiving end.
What setup is required to receive webhooks?
No additional configuration is needed on the client side after onboarding. The only thing that must be provided during onboarding is the webhook endpoint URL, configured per partner or broker. If the URL needs to change later, it can be updated, but only via a manual request - there is no self-service option.
How are webhook requests authenticated and secured?
The webhooks are secured using HMAC signature verification. Each partner is issued a WebhookSecret during onboarding. Partners should validate the HMAC signature on every incoming request and treat the endpoint as public-facing, with protection against malicious or forged payloads.
How are API keys managed, and what identifiers does each partner receive?
API keys can only be generated - they cannot be updated after creation. Each partner is provisioned with AffiliateId, WebhookSecret, and an API key generated internally by TTX.
How does webhook routing work, and can webhooks be delivered to the wrong partner?
Webhooks are routed per API key / per broker, based on the onboarding configuration. Cross-broker delivery is not possible - the system does not route webhooks to unintended recipients. That said, it is still recommended to validate the AffiliateId included in every payload as an additional safeguard.
How are sub-partners handled, and are there scalability concerns?
Sub-partners must be pre-configured on the TTX side before they can receive correctly routed webhook deliveries. For large partner sets, for example 1,000 or more, onboarding should be coordinated in advance, as the volume requires careful planning on the TTX side.
What identifier should be used to correlate bookings in webhook payloads?
Use BookingReference as the primary correlation key. BasketId is intentionally omitted from webhook payloads and should not be relied upon for matching. The payload type used for barcode delivery events is ScheduledEticketDelivery.
What does the onboarding process involve for both sides?
Partners need to provide only their webhook URL, assuming the partner structure is already configured. TTX provides AffiliateId, WebhookSecret, and an internally generated API key in return.
What are the recommended implementation best practices?
  • Validate the webhook signature using HMAC on every request.
  • Use BookingReference as the primary identifier for matching bookings.
  • Validate AffiliateId in every incoming payload.
  • Ensure the webhook endpoint is consistently available and performs well under load.
  • Account for a delay between booking completion and barcode generation.
  • Coordinate sub-partner mapping early in the onboarding process.