Skip to content
Tickply Developers
Documentation menu: Versioning
tickply.com Open Tickply
On this page

Versioning

The version is in the address: /v1. Version 1 is a stable contract from November 11, 2026.

What does not change in v1

  • Paths and methods. An endpoint that exists keeps its path, its method and the scope it needs.
  • Names and types. A field keeps its name and its type. Ids of records are integers; the ids of webhook events and deliveries are UUID strings, and codes (certificates, coupons) are strings.
  • Money. It is always an integer in cents, in the currency (ISO 4217, such as BRL) of the event, course or order. There is no decimal amount anywhere.
  • Dates and times. They are ISO 8601 in UTC, ending in Z (2026-11-20T11:00:00Z); a date without a time, such as issued_on, is YYYY-MM-DD. When you send a date and time without Z or an offset, it is read in the organizer time zone: send it with Z to be sure.
  • Errors. They keep the shape code, message and, when there is one, errors; an existing code keeps its meaning (see errors).
  • Pagination, idempotency and signatures keep working as described in pagination, idempotency and webhooks: the same parameters, the same header and the same signature algorithm.
  • Webhook events. They keep their name and the fields of their body.
  • Days. A day of an event is a session in the fields (session_id, session_ids, sessions); the names stay as they are.

What can change without notice

  • New endpoints, new optional parameters, new fields in responses and in webhook bodies.
  • New error codes, new values in lists of reasons (such as missing in cannot_publish) and new webhook events.
  • The text of message, which is for people, not for code.
  • The order of fields in a JSON object, and the values of the rate limits.

Build so that something new never breaks you: ignore fields, codes and events you do not know.

What needs notice

Removing or renaming anything in the list above is announced in the changelog 90 days ahead, and the old name keeps working until that date. A change that cannot keep the old behavior goes to a new version, /v2, and /v1 keeps answering.

The OpenAPI document, openapi.yaml, always matches the API that answers at https://api.tickply.com/v1.