Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

Added

• Classic eSIM grants: New per-spec esim_type: 'classic' | 'universal' field on POST /bookings, alongside a per-spec email user-key (parallel to external_user_id) and an expires_at field for bounding classic-grant redemption windows. Classic grants surface in the native app via three new Firebase callable functions (list_classic_package_queues, set_classic_package_queue_destination, claim_classic_package_queue).
• New schema fields: package_specifications[].esim_type, package_specifications[].email, package_specifications[].expires_at. BookingResponse.package_queues[].esim_type is returned so partners can correlate which surface each queue redeems against.
• New webhook event classic_package_queue.claimed — fires when a traveler claims a classic-eSIM grant via the native app. Opt-in via webhook_settings.events.classic_package_queue_claimed. Payload: queue_id, booking_id, esim_iccid, user_id, partner_id, is_top_up.
• New guide: Classic eSIM Grants.

Changed

• package.purchased now covers web app purchases: the event fires for a traveler's first purchase of a destination via the Hubby app or web app (previously native app only). Subsequent purchases for a destination the traveler already has continue to fire topup.completed, so you receive exactly one event per purchase.
• package_specifications[].external_user_id description updated — partners can now identify the User via either external_user_id (existing) or email (new) on a per-spec basis.
• POST /redirect-tokens/create now accepts email as an alternative to external_user_id (supply either; external_user_id wins when both are sent). The email path resolves the traveler by email scoped to your partner; the returned token is always keyed on the traveler's external_user_id (assigned automatically if the user — e.g. a classic-grant/email-only traveler — does not have one yet), so the token exchange and WebView session are unchanged.
• departure_date is now server-defaulted to the current date when any spec is esim_type: 'classic' and the partner omits it (skeletal Booking for non-travel grants).

Removed

• external_user_id is no longer returned at the root of the POST /bookings response. It was ambiguous (null for email-keyed bookings, only the first traveler for multi-traveler bookings). Per-traveler identity is available on the package_queues[] fan-out via each entry's uuid. Breaking for any integrator that read the root external_user_id from the booking response.

Deprecated

• time-limited package type: The time-limited package_type is deprecated and should not be used for new integrations. To offer a fixed data allowance that expires after a set period, use a data-limited package with a short package_duration instead. Existing integrations continue to work; the type may be removed in a future API version.

[2.1.0] - 2026-03-23

Added

• Destinations API: New endpoints for retrieving destination information
  • GET /destinations — List all available destinations (countries and regions) with localized names, ISO3 codes, and metadata
  • GET /destinations/{id} — Get a single destination by ID, including its available data bundles (packages)
• New schemas: DestinationResponse, DestinationDetailResponse, DestinationBundleResponse

Removed

• Countries endpoints: GET /countries, GET /countries/packages, and GET /countries/{country}/packages have been removed. Use the new Destinations API instead.

Changed

• Native API tag renamed to Native Integration API for clarity

[1.3.2] - 2026-01-22

Added

• Brand Support: New custom_branding field for booking requests and responses
  • Allows partners to set a specific visual style for the app experience
  • Brand identifier must correspond to a configuration that exists in the Hubby platform
  • Contact support to set up custom branding for your organization
• Departure Location: New departure_location field for booking requests and responses
  • Capture where travelers are departing from (airport code, city name, or address)
  • Provides additional context for the booking

[1.3.1] - 2025-10-27

Added

• Promo Code Claiming: New feature to share claim links instead of promo codes directly
  • Added uuid and claim_url fields to promo code responses
  • New public endpoint POST /api/promo-codes/claim/{uuid} for claiming promo codes with email capture
  • Claim URLs are only included when bookings don't have an email address
  • Immediate email delivery of promo codes upon claiming
  • Perfect for events, marketing campaigns, and lead capture
• Promo Code Retrieval: New endpoint GET /api/promo-codes/{id} for retrieving promo code details
  • Partners can fetch their promo codes with full metadata
  • Includes RBAC authorization for organization-level access control
• Enhanced Promo Code Documentation: Added comprehensive guide on promo code claiming feature

Changed

• Promo code response schema now includes additional metadata fields: iso3, package_type, package_duration

[1.3.0] - 2025-07-27

Added

• Package Type Support: Added support for multiple package types in booking requests
  • package_type parameter with options: starter, data-limited, unlimited, time-limited
  • package_duration parameter to specify package duration in days
  • Default values: data-limited for package type, 365 days for data-limited packages, 2 days for starter and time-limited packages
• Enhanced Package Documentation: Added comprehensive documentation explaining the differences between package types
  • Starter packages: Small data allowance for short duration, ideal for trials (default: 2 days)
  • Data-limited packages: Traditional packages with specific data allowance (default: 365 days)
  • Unlimited packages: Unrestricted data usage with fair use policy
  • Time-limited packages: Fixed data allowance with time constraint for full-speed access
  • Clarification that top-ups are always data-limited packages

Changed

• API Version: Bumped the version to v1.3.0
• Default Package Type: Data-limited packages are now the primary focus and default option

[1.2.0] - 2025-05-12

Added

• Endpoints added for in app integration The first endpoints for in-app integration have been added.
• External ID Support: Added optional external_id property to bookings for better integration with external systems.

Changed

• Destinationless bookings A booking no longer requires a destination to be specified, the destination can now be picked by the end user.
• Bumped the version to v1.2.0

[1.1.0] - 2025-03-16

Added

• HMAC Auth: HMAC Authentication is now the default for this API
• Regen promo codes: Added the option to regenerate codes.

Changed

• Enhanced Entity Details: All models now includes additional metadata fields, such as created_by and updated_at, to provide better context for each..

Fixed

• Time Format Consistency: Standardized all time-related fields to use ISO 8601 format, ensuring consistency across the API.

[1.0.0] - 2023-02-15

Initial Release

• Launched the Hubby eSIM API with core features including creating a booking and fetching packages.