Changelog

2025-10-30 - Schema Version 2.1.0

  • Added service itemization to both the receipt and itinerary schemas
  • Added nullable carrier string to shipment object
  • Added nullable logo_asset_id string to org object
  • Changed brand_color to be case-insensitive for the purpose of schema validation

Update Events

  • Added new schemas for our transit_route update events. See the Events documentation for more details

Deprecation Notices

  • The subscription itemization has been deprecated and will be removed in a future release. The service itemization should be used instead.
  • The logo field has been deprecated and will be removed in a future release. The logo_asset_id field should be used instead.

2025-10-20 - Protocol Update

Beta release of Update Events.

  • Specifying the event_type in the event registration payload filters receivers by subscription.
  • Registration payloads of update events can exclude transaction handles; the handles will be looked up from the original event registration by transaction_id.

2025-07-18 - Protocol Update

Added the Receiver Query API to replace 'check registry' (now deprecated).

2025-06-17 - Schema Version 2.0.0

This is a major version change. The grace period to get all senders and receivers migrated is currently indefinite; both 1.11.0 and 2.0.0 will be supported for the foreseeable future. We will automatically 'downshift' 2.0.0 receipts to 1.11.0 receipts for 'Custodial Receivers' (as needed) to smooth the transition. We will work with all clients directly on this migration, and we will deprecate 1.11.0 when we confirm 100% readiness.

If you’re a sender, please make a plan to migrate from 1.11.0 to 2.0.0. If you’re a Custodial Receiver client, you’ll need to manually update your webhook’s maximum schema version, via the Versa dev portal, to start receiving 2.0.0 data (until you do, you will continue to receive 1.11.0 formatted data).

Why?

The 2.0.0 update incorporates several points of customer feedback. It enables richer 'passenger' profiles for air travel / 'guest' profiles for hotel bookings. And it enables more flexibility around matching and corporate loyalty programs, to increase match rates.

Breaking Changes

  • passenger changes from a string to a new nullable person object (see the Person documentation for details)
  • metadata is removed from flight tickets (and included in the person object)
  • guests is now an array of person objects
  • current_period_start and current_period_end have been renamed current_period_start_at and current_period_end_at for consistency
  • metadata, taxes, adjustments and other arrays that are valid when empty are now also optional and nullable

Other Changes

  • Fixed: place nullable fields are no longer required
  • Fixed: vehicle nullable image is no longer required
  • Fixed: currency now supports cny instead of cnh
  • Added to rental car vehicle
    • license_plate_number (string)
    • vehicle_class (ACRISS car code, four letters)
  • Added adjustment_type enum option: add_on (for e.g. paid seat upgrades)
  • Added website to customer
  • regex pattern validation for vehicle_class, phone, routing_number, last_four and airport codes
  • minimum and maximum bounds for unix timestamps

End of Life

Schema Version 1.10.0 and earlier are now considered at end of life (EOL) and are no longer supported. The registry will not accept new registrations for these versions.

2025-05-01 - Protocol Update

  • Added support for multiple misuse codes in the /report_misuse API
  • Added semantic validation to misuse reporting spec (see Misuse Reporting for more details)

2025-03-31 - Schema Version 1.11.0

  • Made 'payment_type' optional on 'payment'
  • Fixed incorrect definition of nullable enum types ('mode', 'shipment_status', and 'network')

2025-03-13 - Schema Version 1.10.0

  • Made 'merchant' optional on 'third_party'
  • Renamed 'first_party_relation' to 'relation' on 'third_party'

2025-03-10 - Protocol Update

  • Dropped support for receiver_address and receiver_secret on customer credentials
  • All receiving clients were migrated to webhooks

2025-02-28 - React Library v1.10

  • Added a ReceiptWithHistory component to the @versa/react library that supports viewing previous versions of a receipt

2025-02-10 - Protocol Update

  • Added org_id to Sender object in Checkout
  • Added registered_at timestamp to Checkout
  • Added transaction_event_index to Checkout

2025-01-07 - Schema Version 1.9.0

  • Flight itemization change: added optional 'fare' and 'taxes' to the flight ticket, and adjusted the segment 'fare' to be nullable, to support cases where fare and tax info is only available at the parent ticket level and not at the segment level

2024-11-21 - Schema Version 1.8.0

  • Flight itemization change: added 'aircraft_type' to flight segment

2024-11-7 - Schema Version 1.7.0

  • Added 'footer' to top level
  • Added 'supplemental_text' nullable string to footer, which supports Markdown
  • Moved 'actions' into 'footer'
  • Made 'rate' and 'name' optional on 'adjustment'
  • Made 'email', 'address', and 'phone' optional on 'customer'

2024-10-31 - Schema Version 1.6.0

  • Changed 'product_image_url' to 'product_image_asset_id'
  • Changed General itemization 'line_items' to 'items'
  • Added 'metadata' to car_rental
  • Added optional 'seat' string to flight segments
  • Added optional 'metadata' to tickets (for rewards #)
  • Added optional 'metadata' for flight segments (for e.g. meals)
  • Made all 'address' fields optional
  • Change itemized 'subtotal' field to 'amount'—so 'total' and 'subtotal' should appear only in the receipt header

2024-10-18 - Schema Version 1.5.0

  • Omitting optional keys is now allowed and considered equivalent to setting said keys to null
  • Added support for PDF receipt exports in the @versa/react library

2024-10-18 - Protocol Update

2024-10-09 - Protocol Update

  • Added misuse reporting to the receiver client specification (see Misuse Reporting for more details)

2024-10-08 - Schema Version 1.4.0

  • Adding 'invoice_asset_id' and 'receipt_asset_id' to receipt header (see Assets for more details)

2024-09-26 - Schema Version 1.3.0

  • Fields 'actions' and 'payments' no longer accept null
  • Changed 'merchant' schema definition name to 'org'
  • Added 'date' and 'unspsc' to 'line item'
  • Added 'legal_name' to 'org'
  • Collapsed 'lodging_items' up a level to the 'lodging' itemization, meaning the schema no longer supports multiple rooms per receipt

2024-08-27 - Schema Version 1.2.0

  • Added 'metadata' object to customer in receipt header
  • Added 'tz' to address
  • Added 'vat_number' and 'address' to merchant
  • Fields that expect arrays no longer accept null
  • Renamed 'receipt_id' to 'invoice_number' for clarity
  • Renamed all itemized 'total' fields to 'subtotal' for clarity
  • Renamed 'departure_timezone' and 'arrival_timezone' to 'departure_tz' and 'arrival_tz' for consistency
  • Render percentages next to taxes in @versa/react
  • Render customer data in @versa/react

2024-08-21 - Schema Version 1.1.0

  • Added optional timezone field for origin and destination on flight segments
  • Made the card payment network field to be nullable
  • Updated the payment UI component in @versa/react

2024-06-30 - Schema Version 1.0.0

The schema is considered finalized for production use. Core client specifications are stable.

  • Receiver target endpoint and handle registration API
  • AES-GCM-SIV encryption of receipts with registry-provided 32-byte key, by sender
  • HMAC token generation for outgoing payloads by sender
  • HMAC verification of incoming payloads for receiver
  • Reporting invalid payloads back to registry by receiver

2024-05-08 - v0.1.0

Initial release.

Edit this doc on GitHub