When your business needs to integrate ticketing into its existing infrastructure, the quality of the API is decisive. If you are still weighing up your options, our guide on how to choose a ticketing platform covers the key criteria. A badly designed API means months of development, constant bugs and limitations you discover too late. This guide helps you assess what to look for before you commit to a platform.
The good news is that almost nothing you should demand is a matter of opinion. Most of it is written down in public specifications: OpenAPI for the contract, IETF RFCs for authentication, errors and the end of life of an endpoint, and the payment provider's documentation for event delivery. What follows is that list, with the concrete reference alongside.
What does the quality of an API's documentation tell you?
Documentation quality reflects the maturity of the API. Look for these elements:
- OpenAPI/Swagger specification: lets you generate clients automatically
- Code examples: in the languages you use (JS, Python, PHP...)
- Use-case guides: not just a reference, but tutorials too
- Changelog: history of changes and versioning policy
- Status page: visibility of the service's availability
The standard has a name and a date. The OpenAPI Specification 3.1.0 was published on 15 February 2021 and requires an openapi field with the version of the specification the document uses, distinct from the version of the API itself. It supports JSON and YAML, and recommends YAML 1.2 so that conversion between the two loses no information.
The practical contrast is simple. A valid OpenAPI document loads into a generator and produces a typed client in your language within minutes. A PDF or a page of loose examples does not. Ask for the file, not the screenshot: if the provider cannot hand you the openapi.yaml the same day you ask for it, the integration starts with debt.
How should a secure ticketing API authenticate requests?
The API handles sensitive data and financial transactions. Security is non-negotiable.
- OAuth 2.0: the modern standard for authentication
- API keys with scopes: granular permissions per key
- Credential rotation: the ability to rotate without downtime
- Rate limiting: protection against abuse, with documented limits
- Access logs: an audit trail of who accesses what
The base framework is RFC 6749, which defines the OAuth 2.0 Authorization Framework. But what you should bring to the technical meeting is RFC 9700, *Best Current Practice for OAuth 2.0 Security*, published in 2025. Three of its requirements can be checked in an afternoon:
- Authorisation servers must support PKCE, and public clients must use it. It protects against theft of the authorisation code.
- The *redirect URI* must be validated by exact string comparison, with the sole exception of variable ports on
localhostfor native applications. Any pattern matching is an open door. - Access tokens should be bound to the sender by means of mTLS or DPoP, so that a leaked token is useless in other hands.
If the provider only offers a static, never-expiring API key, that is not a deal-breaker, but the contract must cover what that decision implies: real scopes, rotation without interrupting the service and an access log you can export.
Which essential endpoints should the API cover?
Check that the API covers every operation you need.
- Events: create, edit, list, manage statuses
- Tickets: types, prices, availability, reservations
- Orders: create, retrieve, cancel, refund
- Validation: verify tickets, record entries
- Webhooks: event notifications (sale, entry, etc.)
One question decides more than the list above: what happens if the same request arrives twice. In ticketing, a network retry on an order creation can duplicate a sale and block capacity that does not exist. The right answer is an idempotency key for each write operation, so that the second attempt returns the result of the first instead of creating a new order. Ask in writing and ask to see the behaviour in the sandbox.
The second question is pagination and read limits. An API that does not document how many orders it returns per page or how to walk through the history turns any nightly export to your metrics dashboard into an engineering problem of its own.
What are webhooks for in an integration?
Webhooks are critical for keeping your system in sync without constant polling.
- Available events: which actions trigger webhooks
- Documented payload: a clear structure for each event type
- Retries: what happens if your endpoint fails
- Signature verification: to confirm the webhook is authentic
- Logs: history of webhooks sent and their status
How to verify a signature
The best-documented procedure in the industry is Stripe's, and it works as a pattern even if your provider is a different one. Its webhooks documentation describes a Stripe-Signature header with a timestamp prefixed t= and one or more signatures prefixed with a scheme; the only valid scheme in production is v1. The signature is calculated as an HMAC with SHA-256 over the string formed by the timestamp, a full stop and the exact JSON body of the request, using the endpoint secret as the key.
Three details that break real integrations. First: you must use the raw body; if your framework reserialises the JSON, verification always fails. Second: the comparison must be made in constant time, so as not to leak information through response time. Third: the official libraries apply a default tolerance of 5 minutes between the timestamp and the current time, and the documentation itself warns against setting it to zero, because that disables the freshness check and reopens the replay attack.
Retries, duplicates and ordering
Concrete numbers matter when you size your queue. Stripe documents automatic retries for up to three days with exponential backoff in production mode, and three retries over a few hours in sandbox. Manual resending works for up to 15 days from the dashboard and up to 30 days from the CLI. You can register up to 16 endpoints for webhooks.
And two warnings worth copying word for word into your design: the delivery order of events is not guaranteed, and an endpoint may receive the same event more than once. The official recommendation is to log the IDs of events already processed and not to use the creation timestamp to infer order. In addition, the endpoint must return a 2xx before the heavy logic: any 3xx response is treated as a delivery failure, and a *timeout* triggers the retry cycle.
How should the API handle errors and usage limits?
With standard formats, not invented strings. RFC 9457, *Problem Details for HTTP APIs*, published in 2023, defines a machine-readable error body with five fields: type (a URI identifying the problem type), title, status, detail and instance, served as application/problem+json. An API that uses it saves you from writing an error translator for each provider.
For usage limits, the reference is RFC 6585, *Additional HTTP Status Codes*, from April 2012, which introduced the 429 Too Many Requests code. The specification itself says the response should include details explaining the condition and may include a Retry-After header indicating how long to wait. That header is the difference between a considered retry and a loop that makes the overload worse.
In the evaluation, ask what limits the API applies per minute and per key, whether they differ for reads and writes, and what happens at the peaks of an on-sale, which is exactly when your integration calls the most. A platform that does not publish its limits is asking you to discover them on the worst possible day.
Why do I need a test environment (sandbox)?
Developing against production is a recipe for disaster. Insist on a proper sandbox.
- Separate sandbox environment: test data without affecting production
- Test cards: to simulate payments without real charges
- Sample data: events and tickets preloaded for testing
- Parity with production: the same behaviour, the same responses
Add a test that almost nobody runs in an evaluation: forcing errors. A useful sandbox lets you simulate a declined payment, a partial refund, a bank authentication that the buyer abandons and a webhook that arrives late. If you can only test the happy path, you have tested nothing.
The clock matters too. Check that the sandbox lets you bring an event's date forward, so you can verify the close of sales, validation at the door and the generation of later reports without waiting weeks.
What legal obligations does the integration carry?
Two fronts, and neither is optional in the European Union.
The first is payments. Delegated Regulation (EU) 2018/389 requires in Article 4 that authentication be based on two or more elements from the categories of knowledge, possession and inherence, and in Article 5 dynamic linking: the code generated must be specific to the amount and the payee accepted by the payer. Its Article 16 sets out the low-value exemption: transactions of up to EUR 30, with a previous cumulative total not exceeding EUR 100 or a maximum of five consecutive remote transactions. Your integration must know how to return the buyer to the flow after authentication, and that is tested in the sandbox, not on the night of the on-sale. If you sell in Spain, cross-check it with the available payment methods.
The second is data. Regulation (EU) 2016/679 requires in Article 32 the application of appropriate technical and organisational measures, including encryption and the ability to ensure confidentiality and integrity, and in Article 33 the notification of security breaches to the supervisory authority without undue delay and, where feasible, not later than 72 hours. An API that hands you attendees' emails and phone numbers makes you responsible for what you do with them: the data processing agreement is signed before the first call, not after. The operational detail is in our GDPR guide for organisers.
How is an API versioned and deprecated without breaking your integration?
With public rules. Semantic Versioning 2.0.0 reserves the major version increment for changes incompatible with earlier versions, the minor for backwards-compatible functionality and the patch for fixes. Applied to an API, it means a change that breaks your client cannot arrive in a silent deployment on a Tuesday.
There is a standard header for end of life. RFC 8594, from May 2019, defines the Sunset HTTP response field with a single timestamp indicating when the resource is likely to stop responding, and a sunset link relation type to point to the retirement or migration policy. Asking whether the API emits it is a quick way to find out whether the provider has thought about the life cycle or only about the launch.
The same goes for the embedded sales widget: if its JavaScript is served from an unversioned URL, any change by the provider reaches your website without warning.
What technical support should the provider offer?
When something fails at 2 a.m. before your event, you need quick answers.
- Technical channel: access to developers, not just generic support
- Documented SLA: committed response times
- Community: a forum or Slack where you can resolve questions
- Technical onboarding: a guided integration session
Ask for the SLA to state three things with numbers: time to first response by severity, the hours covered and what happens if it is breached. A commitment without consequences is a statement of intent. And ask about the change window: a platform that deploys to production on the Friday of an on-sale has a process problem, not a technology one.
How do I choose the right ticketing API?
A good ticketing API speeds up your development, reduces bugs and lets you build customised experiences. It is also the basis for integrating an embedded sales widget into your own website or connecting your metrics dashboard. A bad API traps you in limitations you discover too late. Invest time in evaluating before you commit: ask for sandbox access, test the critical endpoints and talk to the technical team. The right decision will save you months of frustration.
Nine concrete checks for that evaluation:
- Ask for the OpenAPI file, not the HTML documentation. If it does not exist, generate the client yourself and add it to the project cost.
- Demand PKCE and exact redirect URI validation if there is OAuth 2.0, as RFC 9700 requires.
- Test idempotency: send the same order creation twice and check that only one is created.
- Verify a webhook signature by hand before trusting the library, and set a time tolerance other than zero.
- Make your endpoint fail on purpose and measure how many retries arrive, for how long and with which headers.
- Duplicate a webhook and check that your system does not sell the same ticket twice.
- Ask about usage limits per key and whether the API returns
429withRetry-After. - Check the error format:
application/problem+jsonwithtype,title,status,detailandinstancesaves weeks. - Ask about the Sunset header and the versioning policy before you sign, not when the notice arrives.
Sources
- OpenAPI Specification v3.1.0, 15 February 2021 (OpenAPI Initiative)
- OpenAPI/Swagger Specification (SmartBear, Swagger)
- OAuth 2.0, official page of the standard
- RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
- RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
- RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
- RFC 6585: Additional HTTP Status Codes, April 2012 (IETF)
- RFC 8594: The Sunset HTTP Header Field, May 2019 (IETF)
- Semantic Versioning 2.0.0, specification in Spanish
- Receive Stripe events in your webhook endpoint, official Stripe documentation
- Delegated Regulation (EU) 2018/389, regulatory technical standards for strong customer authentication (EUR-Lex)
- Regulation (EU) 2016/679, General Data Protection Regulation (EUR-Lex)
