Receipt Schema

Itemized receipts are the core data model of Versa. They include both “header” information — the merchant name, merchant logo, total purchase amount, purchase date, etc. — as well as “line item” details — the quantity, description, and cost of each item purchased.

Technically, the Versa receipt object is an “invoice” combined with an associated payment. In certain pre-purchase scenarios, the invoice and the payment are decoupled, however in most Versa cases, the invoice and payment confirmation come through together, composing the complete receipt in a single payload.

A JSON Schema document and corresponding TypeScript Types are available on GitHub or via the @versa/schema package.

Versa receipts are composed of four sections:

Header: Top-level fields, e.g. merchant details, receipt total, purchase date.
Itemization: Description, quantity, unit cost, and total for each line item. Type-specific templates describe special receipt types, e.g. flight, e-commerce purchase, service.
Actions: Optional merchant-defined links, pivoting off the purchase. For example: ‘Contact Support,’ ‘Buy Again,’ ‘Manage Subscription.’
Payments: Payment status and details.

Rough diagram of receipt elements.

Wrapper

Receipts are wrapped in an object that includes the schema version. The overall Versa receipt structure looks like this:

{
  "schema_version": "2.1.0",
  "header": { ... },
  "itemization": { ... },
  "payments": [ ... ],
  "footer": { ... }
}

Field	Type	Description
`schema_version`	`string`	Version of the receipt schema; useful for validating the receipt.
`header`	`object`	Receipt header.
`itemization`	`object`	Receipt itemization object.
`payments`	`nullable array`	List of payments.
`footer`	`object`	The footer includes actions and supplemental text.

Below we cover each of these sections in detail.

The receipt header is the 10,000 foot view of the transaction, describing the “who,” “when,” and “where” (the “what” is covered in the itemization section). An example receipt header:

"header": {
  "currency": "USD",
  "subtotal": 5928,
  "total": 6332,
  "paid": 6332,
  "invoiced_at": 1713295619,
  "invoice_number": "1024",
  "mcc": 3234,
  "third_party": null,
  "customer": null,
  "location": null,
  "invoice_asset_id": "asset_6dbca44449094eb28aaa6b3c6b2aa4",
  "receipt_asset_id": null
}

Field	Type	Description
`currency`	`string`	An ISO 4217 currency code, e.g. `USD`.
`subtotal`	`integer`	Receipt subtotal (before taxes, fees, tip).
`total`	`integer`	Receipt total amount. This amount is in the receipt currency and in the smallest currency unit.
`paid`	`integer`	Sum of all payments. Will equal `total` if the invoice is paid in full.
`invoiced_at`	`integer`	Time at which the invoice was created. Measured in seconds since the Unix epoch.
`invoice_number`	`nullable string`	Unique identifier for the invoice / receipt.
`mcc`	`nullable string`	Merchant Category Code. This value should match the value on the card network.
`third_party`	`nullable object`	Third party involved in the transaction, where applicable.
`customer`	`nullable object`	Customer involved in the transaction, where applicable.
`location`	`nullable object`	Place object for the merchant. Also where you can set the primary timezone.
`invoice_asset_id`	`nullable string`	Asset id of uploaded invoice PDF or image.
`receipt_asset_id`	`nullable string`	Asset id of uploaded receipt PDF or image.

Third Party Object

Third Party

Use the optional third party object in cases where the sender is a platform / broker. For example, if a coffee shop uses Square to process sales, the ‘sending merchant’ would be Square and the ‘third party merchant’ would be the coffee shop. The make_primary flag specifies whether the sending merchant or the third party merchant should get top billing on the receipt.

Field	Type	Description
`relation`	`enum`	One of `bnpl`, `delivery_service`, `marketplace`, `payment_processor`, `platform`, `point_of_sale`.
`make_primary`	`boolean`	Determines whether the merchant or third party gets top billing on the receipt.
`merchant`	`nullable object`	An org object representing the third party.

Customer Object

Customer

Used in cases where the merchant has a profile for the customer. Can be left null i.e. for guest checkout flows.

Field	Type	Description
`name`	`string`
`email`	`nullable string`
`website`	`nullable string`
`address`	`nullable object`	An address object.
`phone`	`nullable string`	Phone number in the E.164 format.
`metadata`	`array`	Array of metadata objects, for any additional info.

Itemization

The Itemization section describes the goods and services that compose the purchase. Based on the type of purchase, the object conforms to one of seven templates: General, Car Rental, E-commerce, Flight, Lodging, Service, or Transit Route. Exactly one itemization template must be non-null. When in doubt, use the 'general' template.

"itemization": {
  "general": { ... },
  "car_rental": null,
  "ecommerce": null,
  "flight": null,
  "lodging": null,
  "service": null,
  "transit_route": null
}

General Object

General

Field	Type	Description
`items`	`array`	An array of generic item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Car Rental Object

Car Rental

View a complete car rental receipt example.

"car_rental": {
  "rental_at": 1713196492,
  "return_at": 1713415500,
  "rental_location": { ... },
  "return_location": { ... },
  "vehicle": {
    "description": "Polestar 2",
    "image": null,
    "license_plate_number": null,
    "vehicle_class": "EDAE"
  },
  "driver_name": "Henry Ford",
  "odometer_reading_in": 100,
  "odometer_reading_out": 210,
  "items": [ ... ],
  "metadata": [],
  "invoice_level_adjustments": [],
}

Field	Type	Description
`rental_at`	`integer`	Rental time. Measured in seconds since the Unix epoch.
`return_at`	`integer`	Return time. Measured in seconds since the Unix epoch.
`rental_location`	`object`	A place describing the rental location.
`return_location`	`object`	A place describing the return location.
`vehicle`	`object`	A vehicle object.
`driver_name`	`nullable string`
`odometer_reading_in`	`nullable integer`
`odometer_reading_out`	`nullable integer`
`items`	`array`	An array of generic item objects.
`metadata`	`array`	Array of metadata objects, for any additional info.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Vehicle

Field	Type	Description
`description`	`string`	Type of car.
`image`	`nullable string`	Image of car.
`license_plate_number`	`nullable string`
`vehicle_class`	`nullable string`	ACRISS car code, four letters.

E-commerce Object

E-commerce

For online orders, with shipping info. If items have not been assigned to a shipment, add those items to invoice_level_line_items. Once they’ve been assigned to a shipment, move them to shipment.items. View a complete E-commerce receipt example.

Field	Type	Description
`invoice_level_line_items`	`array`	An array of item objects at the invoice level. For items that are part of shipment, move them under the shipment object.
`shipments`	`array`	An array of shipment objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Shipment

Field	Type	Description
`items`	`array`	An array of item objects at shipment level.
`carrier`	`nullable string`	Shipping carrier name (e.g., "FedEx", "UPS").
`tracking_number`	`nullable string`	Label that appears on the button.
`expected_delivery_at`	`nullable int`	Measured in seconds since the Unix epoch.
`shipment_status`	`nullable enum`	One of `prep`, `in_transit`, `delivered`.
`destination_address`	`nullable object`	An address object.

Flight Object

Flight

View a complete flight receipt example.

Field	Type	Description
`tickets`	`array`	An array of ticket objects.
`itinerary_locator`	`nullable string`
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Tickets

Field	Type	Description
`segments`	`array`	Array of segments.
`number`	`nullable string`
`record_locator`	`nullable string`	PNR.
`passenger`	`nullable object`	A person object.
`metadata`	`array`	Array of metadata objects, for any additional info.
`fare`	`nullable integer`	Optional, only needed if fares are not included on the contained segments.
`taxes`	`array`	Optional, only needed if taxes are not included on the contained segments.

Segments

Field	Type	Description
`departure_airport_code`	`string`	The three-letter IATA airport code that the flight departed from.
`arrival_airport_code`	`string`	The three-letter IATA airport code of the flight’s destination.
`fare`	`nullable integer`	Should be included, unless `fare` is on the parent ticket object instead.
`taxes`	`array`	Array of tax objects.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`departure_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`arrival_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`flight_number`	`nullable string`	The two-letter IATA airline designator followed by a one to four digit number (e.g. 'DL123').
`class_of_service`	`nullable string`
`seat`	`nullable string`
`aircraft_type`	`nullable string`	The ICAO code of the aircraft.
`metadata`	`array`	Array of metadata objects, for any additional info.
`adjustments`	`array`	Array of adjustment objects.

Lodging Object

Lodging

View a complete lodging receipt example.

lodging: {
  "check_in": 1713196492,
  "check_out": 1713473361,
  "guests": [{
    "first_name": "Susan",
    "last_name": "Doe",
    "preferred_first_name": "Sue",
    "email": "sdoe@platform.co",
    "phone": "+14155552671",
    "metadata": []
  }],
  "room": "806",
  "location": { ... },
  "items": [ ... ],
  "metadata": [],
  "invoice_level_adjustments": []
}

Field	Type	Description
`check_in`	`int`	Check-in date-time. Measured in seconds since the Unix epoch.
`check_out`	`int`	Check-out date-time. Measured in seconds since the Unix epoch.
`guests`	`array`	Array of person objects.
`room`	`nullable string`	Room number.
`location`	`nullable object`	A place object describing the hotel / lodging.
`items`	`array`	An array of generic item objects. This includes the room rate, as well as incidentals / full folio.
`metadata`	`array`	Array of metadata objects, for any additional info.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Service Object

Service

For airport parking, SaaS subscriptions, phone bills, etc. View a complete service receipt example.

"service": {
  "service_items": [{
    "recurring": true,
    "description": "Pro monthly plan",
    "amount": 1000,
    "interval": "month",
    "interval_count": 1,
    "current_period_start_at": 1679609767,
    "current_period_end_at": 1682288167,
    "quantity": 10,
    "unit_cost": 875,
    "taxes": [],
    "metadata": [],
    "adjustments": []
  }],
  "invoice_level_adjustments": []
}

Field	Type	Description
`service_items`	`array`	An array of service item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Service Item

Field	Type	Description
`amount`	`integer`	Subtotal for the line item (typically `quantity` × `unit_cost` + `adjustments`). Does not include `taxes`.
`service_location`	`nullable object`	A place object describing the location where the service was provided (e.g., parking lot, service center).
`recurring`	`boolean`	Whether this is a recurring service.
`description`	`string`	Description of the service.
`interval`	`nullable enum`	One of `day`, `week`, `month` or `year`.
`interval_count`	`nullable integer`	The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.
`current_period_start_at`	`nullable integer`	Start of the current period of the service. Measured in seconds since the Unix epoch.
`current_period_end_at`	`nullable integer`	End of the current period. Measured in seconds since the Unix epoch.
`quantity`	`nullable number`	Quantity of items.
`unit_cost`	`nullable integer`	Cost of the service in the smallest currency unit.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.
`adjustments`	`array`	Array of adjustment objects.

Transit Route Object

Transit Route

A route, typically used by rideshare / taxi services, or rail / bus / ferry / etc. View complete taxi receipt or rail receipt examples.

"transit_route": {
  "transit_route_items": [{
    "departure_address": {
      "street_address": "273 Sesame St",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.68266,
      "lon": -73.94237,
      "tz": "America/New_York"
    },
    "arrival_address": {
      "street_address": "141 Broadway",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.69954,
      "lon": -73.97064,
      "tz": "America/New_York"
    },
    "fare": 4215,
    "departure_at": 1713196492,
    "arrival_at": 1713197752,
    "passenger": null,
    "polyline": "syhwFxzhbMrFtdAmpAhOlGzmAi%5CdEaGEDgEoAEMfK",
    "taxes": [],
    "metadata": [],
    "adjustments": []
  }],
  "invoice_level_adjustments": []
}

Field	Type	Description
`transit_route_items`	`array`	Array of transit route item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Transit Route Item

Field	Type	Description
`departure_location`	`object`	The origin place object.
`arrival_location`	`object`	The destination place object.
`fare`	`integer`	Ride amount, typically the same as the header subtotal.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`mode`	`nullable enum`	One of `car`, `taxi`, `rail`, `bus`, `ferry`, `other`.
`passenger`	`nullable object`	A person object.
`polyline`	`nullable string`	An encoded polyline of the route.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs.
`adjustments`	`array`	Array of adjustment objects.

Field	Type	Description
`actions`	`array`	List of actions.
`supplemental_text`	`nullable string`	Terms and conditions or other info. Supports Markdown.

Actions

Merchants have the option to provide useful next actions in the Actions section. An action is typically a deep link to a page within the merchant’s website. For example 'Buy Again' might deep link to a pre-filled shopping cart. There is a limit of three actions per receipt.

NOTE

For security reasons, we recommend that the action urls share the same domain as the sending merchant, wherever possible. Action URLs that don’t share a domain with the sending merchant may be filtered by the receiver.

"actions": [
  {
    "name": "Emergency Roadside Assistance",
    "url": "https://yourco.com/support/be1e1b57-8fe9-4729-8b7d-f9a4690bb2cd"
  },
  {
    "name": "Rebook",
    "url": "https://yourco.com/buy/ad058b82-d0dd-4534-a915-d448df098167"
  }
]

Field	Type	Description
`name`	`string`	Label that appears on the button.
`url`	`string`	Action deep link.

Payments

"payments": [
  {
    "paid_at": 1679609767,
    "payment_type": "card",
    "amount": 234,
    "card_payment": {
      "last_four": "7806",
      "network": "mastercard"
    },
    "ach_payment": null
  }
]

Field	Type	Description
`amount`	`int`
`paid_at`	`int`	Measured in seconds since the Unix epoch.
`payment_type`	`nullable enum`	One of `card` or `ach`.
`card_payment`	`nullable object`	Card payment object.
`ach_payment`	`nullable object`	ACH payment object.

Card Payment Object

Card Payment

Field	Type	Description
`last_four`	`string`	The last four digits of the card number.
`network`	`nullable enum`	One of `amex`, `diners`, `discover`, `eftpos_au`, `jcb`, `mastercard`, `unionpay`, or `visa`.

ACH Payment Object

ACH Payment

Field	Type	Description
`routing_number`	`string`	ACH routing number.

Primitives

Foundational objects used in a variety of locations within the receipt schema.

Org Primitive

Org

A merchant, third party, or employer profile.

TIP

The org object is used to describe both a sending merchant and a third party merchant. In the former case, the org object is expanded implicitly via the Versa Registry, whereas in the latter case, the org object is explicitly encoded into the receipt, via the header third_party object.

{
  "name": "Some Co",
  "legal_name": "Some Co, Inc.",
  "brand_color": "#f0C14B",
  "logo": "https://static.platform.co/image_url.png",
  "logo_asset_id": "asset_6dbca44449094eb28aaa6b3c6b2aa4",
  "website": "platform.co",
  "vat_number": null,
  "address": null
}

Field	Type	Description
`name`	`string`	The organization's common name.
`legal_name`	`nullable string`	The organization's legal name.
`brand_color`	`nullable string`	Hex color.
`logo`	`nullable string`	⚠️ Deprecated: Logo image url, in a square aspect ratio. Use `logo_asset_id` instead.
`logo_asset_id`	`nullable string`	Asset id of uploaded logo image. Recommended size 400x400 in a square aspect ratio.
`website`	`nullable string`	Organization's primary website url.
`vat_number`	`nullable string`
`address`	`nullable object`	An address object.

Person Primitive

Person

{
  "first_name": "Theodore",
  "last_name": "Doe",
  "preferred_first_name": "Ted",
  "email": "tdoe@platform.co",
  "phone": "+14155552671",
  "metadata": []
}

Field	Type	Description
`first_name`	`nullable string`	Legal first name.
`last_name`	`nullable string`	Legal last name.
`preferred_first_name`	`nullable string`
`email`	`nullable string`
`phone`	`nullable string`	Phone number in the E.164 format.
`metadata`	`array`	Array of metadata objects, for any additional info.

Place Primitive

Place

Describes a brick-and-mortar location.

{
  "name": "Widget Co",
  "address": {
    "tz": "America/New_York"
  },
  "phone": "+14155552671",
  "url": null,
  "google_place_id": null,
  "image": null
}

Field	Type	Description
`name`	`nullable string`	Place name.
`address`	`nullable object`	An address object.
`phone`	`nullable string`	Phone number in the E.164 format.
`url`	`nullable string`	URL for specific place, e.g. chain.com/store-id.
`google_place_id`	`nullable string`	Mapping to the Google Places database.
`image`	`nullable string`	Image representing the place.

Address Primitive

Address

{
  "street_address": "123 Main St",
  "city": "Anytown",
  "region": "CA",
  "country": "US",
  "postal_code": "12345",
  "lat": 37.7749,
  "lon": -122.4194,
  "tz": "America/Los_Angeles"
}

Field	Type	Description
`street_address`	`nullable string`
`city`	`nullable string`
`region`	`nullable string`	Two letter region code.
`country`	`nullable string`	Two letter ISO 3166 country code.
`postal_code`	`nullable string`
`lat`	`nullable number`
`lon`	`nullable number`
`tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.

Item Primitive

Item

A generic line item.

{
  "description": "Blue Cheese Crumbles",
  "amount": 1780,
  "quantity": 10,
  "unit_cost": 178,
  "unit": null,
  "product_image_asset_id": null,
  "group": null,
  "unspsc": null,
  "url": null,
  "date": null,
  "taxes": [
    {
      "amount": 432,
      "rate": 0.0875,
      "name": "GST"
    }
  ],
  "metadata": [{ "key": "SKU", "value": "524959" }],
  "adjustments": []
}

Field	Type	Description
`description`	`string`	Description of the good / service.
`amount`	`integer`	Subtotal for the line item (typically `quantity` × `unit_cost` + `adjustments`). Does not include `taxes`.
`quantity`	`nullable number`	Quantity of items.
`unit_cost`	`nullable integer`	Cost of the good / service in the smallest currency unit.
`unit`	`nullable string`	Field describing the unit type, typically for weight or volume -based values, e.g. 'kg' or 'gallons'. Leave null for 'each'.
`product_image_asset_id`	`nullable string`	Asset id of uploaded product image.
`group`	`nullable string`	Grouping of line items.
`unspsc`	`nullable string`	The 8-digit UNSPSC code for this item.
`url`	`nullable string`	URL to product page.
`date`	`nullable string`	Date corresponding to the line item, in ISO 8601 format (YYYY-MM-DD), e.g. for nightly rate in a hotel folio.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.
`adjustments`	`array`	Array of adjustment objects.

Metadata Primitive

Metadata

Use line item metadata to track things not otherwise in the schema. E.g. SKU, Size, Color, UNSPSC Code, etc.

{
  "key": "SKU",
  "value": "524959"
}

Field	Type	Description
`key`	`string`	The type of metadata, e.g. 'Size', 'Brand', 'Product Condition', 'Special Instructions', etc.
`value`	`string`	The corresponding value.

Tax Primitive

Tax

{
  "amount": 432,
  "name": "GST",
  "rate": 0.0875
}

Field	Type	Description
`amount`	`int`	The total tax, in the smallest currency unit.
`name`	`string`	E.g. 'VAT' or 'GST'.
`rate`	`nullable number`	The tax rate, e.g. 0.05 for 5%.

Adjustment Primitive

Adjustment

To be used for discounts, tip, fees, surcharges, tolls.

{
  "amount": 1234,
  "adjustment_type": "tip",
  "name": "Tip",
  "rate": null
}

Field	Type	Description
`amount`	`int`	The total of the adjustment, in the smallest currency unit. Positive value for tip / fee, negative value for discount.
`adjustment_type`	`enum`	One of `discount`, `tip`, `fee`, `add_on`, `other`.
`name`	`nullable string`	The name of the adjustment.
`rate`	`nullable number`	The adjustment rate, e.g. -0.1 for 10% discount, or 0.2 for 20% tip. Null for fixed adjustment.

Definitions & Formatting

Currency Values

All API requests expect amounts to be provided in a currency’s smallest unit. For example, to represent 10 USD, provide an amount value of 1000 (that is, 1000 cents). For zero-decimal currencies, still provide amounts as an integer but without multiplying by 100. For example, to represent ¥500, provide an amount value of 500.

Images

Images must be hosted at public URLs. The images are likely to be indexed by the receiver. For best results, no image dimension should be less than 400px, or greater than 2,000px.

Edit this doc on GitHub