# HeroJSON Specification ### Merchant object ```javascript "merchant": { "name": "Global Receipt Delicatesse", "companyID": "123456-7", "branch": { "id": "340", "posId": "2", "name": "Receipt Restaurant", "subName":"FastFood", "email": "restaurant@example.com", "phone": "040-5086462", "websiteURL": "https://www.getreceipthero.com/", "address": { "streetAddress": "Itsenäisyydenkatu 17 a 15", "city": "Tampere", "zipCode": "33500", "country": "Finland" } } ``` | Key | Type | Description | Required | | ------------- | ------ | ----------------------------------- | :------: | | **name** | String | Company name | ✅ | | **companyID** | String | Company's business id or VAT number | ✅ | #### Branch object | Key | Type | Description | Required | | ------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- | :------: | | **id** | String | Unique identifier for a branch (e.g., cost center number or another identifier used to distinguish branches of a Merchant) | ✅ | | **posId** | String | Logical cash register id | ✅ | | **name** | String | Branch name | ✅ | | subName | String | Freetext slogan etc, placed under branch name | | | email | String | Email address to branch / company support | | | phone | String | Phone number to branch / company support | | | websiteURL | String | Website URL of branch / company | | | **address** | Object | Address values | ✅ | | :wavy\_dash: **streetAddress** | String | Branch location street address | ✅ | | :wavy\_dash: **city** | String | Branch location city | ✅ | | :wavy\_dash: **zipCode** | String | Branch location zip code | ✅ | | :wavy\_dash: **country** | String | Branch location country | ✅ | ### Products array Products array contains all product on receipt ```javascript "products": [ { "name": "Ground Control", "EANCode": "42222130165", "quantity": "4", "productId": "1234", "quantityCode": "PCS", "freeText": "Product instructions etc", "categorization": { "main": "12", "product": "122", "sub": "1224" }, "unitPriceIncVAT": 5180, "unitPriceIncVATDecimal": "51,80", "totalAmountExcVAT": 18836, "totalAmountIncVAT": 20720, "vats": [ { "VATRate": "24", "VATAmount": 1884, "totalAmountExcVAT": 18836, "totalAmountIncVAT": 20720 } ], "discounts": [ { "amount": 0, "percentage": "0.00", "description": "" } ], "customAttributes": [ { "Warranty": "2 years" }, { "Valid until": "2020-11-26" } ] } ], ``` | Key | Type | Description | Required | | ---------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | **name** | String | Product name | ✅ | | EANCode | String | Product EAN code | | | **quantity** | String | Quantity of product | ✅ | | productId | String | Merchants internal productID | | | **quantityCode** | String | Quantity code for product | ✅ | | freeText | String | Product related text field | | | **unitPriceIncVAT** | Integer |

Unit price including VAT in

fractional unit (Cents in Euros etc.)

| ✅ | | unitPriceIncVATDecimal | String |

Unit price including VAT in
main currency unit. Mainly used by petrol receipts

| | | **totalAmountExcVAT** | Integer | Total price for product row without VAT in fractional unit | ✅ | | **totalAmountIncVAT** | Integer | Total price for product row with VAT in fractional unit | ✅ | | **vats** | Array |

Product level VAT specifications

One object represents one VAT rate.

If product has multiple taxrates -> multiple objects

| ✅ | | :wavy\_dash: **VATRate** | String | VAT rate. Integer or Decimal | ✅ | | :wavy\_dash: **VATAmount** | Integer | VAT amount in fractional unit | ✅ | | :wavy\_dash: **totalAmountExcVAT** | Integer | Amount without VAT in fractional unit | ✅ | | :wavy\_dash: **totalAmountIncVAT** | Integer | Amount with VAT in fractional unit | ✅ | | discounts | Array | Product level discount objects. | | | :wavy\_dash: **amount** | Integer | Amount of discount in fractional unit | ✅ | | :wavy\_dash: percentage | String | Discount percentage in decimal | | | :wavy\_dash: **description** | String | Discount reason in free text | ✅ | | customAttributes | Array |

Key value pair for custom attributes on product

These key value pair will be shown on receipt as table under product.

| | | :wavy\_dash: **key** | String | Free key name | ✅ | | :wavy\_dash: **value** | String | Free value | ✅ | #### Product Categorization ```json "categorization": { "main": "12", "product": "122", "sub": "1224", "tags": ["stampcard-identifier"] } ``` | Key | Type | Description | Required | | ----------- | ------------ | ---------------------------------------------------------------------------------------------------- | :------: | | main | String | Main category identifier | | | **product** | String | Product category identifier | ✅ | | sub | Integer | Sub category identifier | | | tags | String Array | A list of custom tags, used for purposes such as marking a product's inclusion in a stamp card offer | | #### Product Journey When dealing with travel-related products such as bus, train, taxi, or other transportation services, it is possible to include structured journey details alongside the product line item. The journey object allows specifying relevant metadata such as the type of transport, schedule, distance, emissions, and location data for both origin and destination. ```json "journey": { "type": "TRAIN", "id": "IC924", "distance": 185000, "duration": 120, "CO2Emissions": 222, "origin": { "name": "Pasila", "city": "Helsinki", "country": "Finland", "latitude": "60.1988", "longitude": "24.9333", "datetime": "2025-04-02T10:00:00+02:00" }, "destination": { "name": "Turku (City Centre, Logomo)", "city": "Helsinki", "country": "Finland", "latitude": "60.45694", "longitude": "22.25750", "datetime": "2025-04-02T12:00:00+02:00" } } ``` #### Journey Object
KeyTypeDescriptionRequired
typeString

Type of Journey

  TRAIN
  BUS
  TAXI
  FLIGHT
  FERRY
✅
idStringJourney identifier, such as train connection or flight number
distanceNumberJourney distance in meters
durationNumberJourney duration in minutes
CO2EmissionsIntegerCO2 Emissions in grams
origin#journey-location-objectJourney origin✅
destination#journey-location-objectJourney destination✅
vehicle#journey-vehicle-objectJourney vehicle, applicable for type=TAXI
driver#journey-driver-objectDriver details, applicable for type=TAXI
pickupArrivedAtStringDeparture or Arrival time as ISO 8601 datetime with offset
#### Journey Location Object
KeyTypeDescriptionRequired
nameStringJourney location name✅
cityStringJourney location city
countryStringJourney location country
latitudeStringJourney location latitude
longitudeStringJourney location longitude
datetimeStringDeparture or Arrival time as ISO 8601 datetime with offset
#### Journey Vehicle Object Optional vehicle details for the journey. Currently applicable only to `TAXI` journeys.
KeyTypeDescriptionRequired
idStringVehicle identifier✅
licensePlateStringVehicle license plate number✅
makeStringVehicle make
modelStringVehicle model
categoryString

Vehicle category

  SEDAN
  HATCHBACK
  WAGON
  VAN
  MINIBUS
  SUV
  LUXURY
powertrainString

Vehicle power train

  PETROL
  DIESEL
  HYBRID
  PLUG_IN_HYBRID
  ELECTRIC
  HYDROGEN
phoneNumberStringVehicle phone number
#### Journey Driver Object Optional vehicle details for the journey. Currently applicable only to `TAXI` journeys.
KeyTypeDescriptionRequired
idStringDriver identifier✅
### Receipt VAT specification ```javascript "vats": [ { "VATRate": "24", "totalVATAmount": 1884, "totalAmountExcVAT": 18836, "totalAmountIncVAT": 20720, "VATCode": "A" } ], ``` | Key | Type | Description | Required | | ---------------------------------- | ------- | --------------------------------------------------- | :------: | | **vats** | Array | Receipt total VATs as array of objects per VAT rate | ✅ | | :wavy\_dash: **VATRate** | String | VAT rate. Integer or Decimal | ✅ | | :wavy\_dash: **totalVATAmount** | Integer | VAT amount in fractional unit | ✅ | | :wavy\_dash: **totalAmountExcVAT** | Integer | Amount without VAT in fractional unit | ✅ | | :wavy\_dash: t**otalAmountIncVAT** | Integer | Amount with VAT in fractional unit | ✅ | | VATCode | String | VAT identifier | | ### Payments HeroJSON supports a variety of payment types including card, cash, gift card, and online payments — see the full list of [payment-types](https://docs.receipthero.io/filetypes/receipthero-json/herojson-specification/payment-types "mention") for details. Payments are mapped as an array of Payment Objects as shown in the example below. #### Payments Example ```json "payments": [ { "type": "CARD", "amount": 20720, "attributes": { "transactionType": "PURCHASE", "currencyISOCode": "EUR", "MID": "12346543", "timeStamp": "2022-09-01T12:35:34.678+02:00", "terminalId": "BS-4545F9", "referenceNumber": "220901015555", "authorizationCode": "HIU456", "transactionId": "05555", "receiptNumber": "12923", "maskedPAN": "525400******9876", "APP": "MASTERCARD DEBIT", "cardType": "DEBIT", "cardProgram": "Nordic Tech Bank — MC Debit", "transactionRawText": "CARD TRANSACTION\n\nCard: Debit Mastercard\n **** **** **** 9876 LN\nApplication: A0000000041010\nTr.Nr/Auth: 05555/HIU456\nPayee/business: 0029432413000/0001\n\nReference: 220901015555\n\nCredit/Charge 207,20 EUR\nPayPass Contactless \n\n", "preAuthorizedAmount": 30000, "ENTRY": "Contactless ICC (07)", "ARC": "APPROVED (00)", "TVR": "8000008000", "TSI": "E800", "AID": "A0000000031010", "AC": "9F270180", "CID": "0x80", "cryptogramType": "ARQC", "CVM": "Online PIN" } }, { "type": "CASH", "amount": 34920, "attributes": { "handedAmount": 40000 } } ] ``` ### General Receipt Data ```javascript "type": "PURCHASE", "customAttributes": [ { "key": "value" }, { "key2": "value2" }, { "key3": "value3" } ], "freeText": "Custom greetings etc", "receiptNumber": "89942344234", "receiptTimeStamp": "2018-11-26T12:35:34.678+02:00", "currencyISOCode": "EUR", "totalVATAmount": 1884, "totalPriceExcVAT": 18836, "totalPriceIncVAT": 20720, } ```
KeyTypeDescriptionRequired
typeString

Type of Receipt

PURCHASE
RETURN
PURCHASE_AND_RETURN
freeTextStringFreetext field to be displayed on receipt
receiptNumberStringMerchant's internal receiptnumber✅
receiptTimeStampStringISO 8601 datetime with offset✅
currencyISOCodeStringCurrency code✅
totalVATAmountIntegerTotal VAT amount in fractional unit✅
totalPriceExcVATIntegerTotal price excluding VAT✅
totalPriceIncVATIntegerTotal price including VAT✅
customAttributesArrayKey value pair list, to be show on receipt
〰️ KeyStringFree text key✅
〰️ ValueStringFree text value✅
### Verifications array ```json "verifications": [ { "type": "OCMF", "version": "1.0", "publicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEqHEykfqZhspgok6zCQh/329B38xine8ujzT8p5Nh7lek47cYeZj507aN6E4/QirF1b7Q57ln4VGfK6h0d0GOQA==", "transactionId": "848182519", "currentType": "AC", "transactionBegin": { "signedData": "OCMF|{\"FV\" : \"1.0\",\"GI\" : \"Nano CH-10311C\",\"GS\" : \"060643\",\"GV\" : \"v017\",\"PG\" : \"T198\",\"MV\" : \"DZG\",\"MM\" : \"DVH4013\",\"MS\" : \"1DZG0033016824\",\"IS\" : true,\"IL\" : \"VERIFIED\",\"IF\" : [\"RFID_NONE\",\"OCPP_NONE\",\"ISO15118_NONE\",\"PLMN_NONE\"],\"IT\" : \"EMAID\",\"ID\" : \"04ab076a345b85\",\"CT\" : \"CBIDC\",\"CI\" : \"CI\",\"RD\" : [{\"TM\" : \"2021-10-26T10:20:52,000+0200 I\",\"TX\" : \"B\",\"RV\" : \" 9.038\",\"RI\" : \"01-00:01.08.00.FF\",\"RU\" : \"kWh\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"}]}|{\"SA\" : \"ECDSA-secp256k1-SHA256\",\"SD\" : \"3046022100A4C188533ECA1793336520F7F99E010E62DEC32ABD344A562B00D396F65DFFE9022100CB0FB3782E406525641D689F4326D2118365A722EE75AAAB976C14B090BE49DA\"}" }, "transactionEnd": { "signedData": "OCMF|{\"FV\" : \"1.0\",\"GI\" : \"Nano CH-10311C\",\"GS\" : \"060643\",\"GV\" : \"v017\",\"PG\" : \"T199\",\"MV\" : \"DZG\",\"MM\" : \"DVH4013\",\"MS\" : \"1DZG0033016824\",\"IS\" : true,\"IL\" : \"VERIFIED\",\"IF\" : [\"RFID_NONE\",\"OCPP_NONE\",\"ISO15118_NONE\",\"PLMN_NONE\"],\"IT\" : \"EMAID\",\"ID\" : \"04ab076a345b85\",\"CT\" : \"CBIDC\",\"CI\" : \"CI\",\"RD\" : [{\"TM\" : \"2021-10-26T10:21:22,000+0200 I\",\"TX\" : \"E\",\"RV\" : \" 9.038\",\"RI\" : \"01-00:01.08.00.FF\",\"RU\" : \"kWh\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"},{\"TM\" : \"2021-10-26T10:21:22,000+0200 I\",\"TX\" : \"E\",\"RV\" : \" 30\",\"RI\" : \"01-00:00.08.06.FF\",\"RU\" : \"sec\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"}]}|{\"SA\" : \"ECDSA-secp256k1-SHA256\",\"SD\" : \"3045022016FD6DF51EE338CC56F6035670172653C93A77F263B7B24DD5DC84EF7C4A98AB022100ADE8D7D9EC4EFFE2B3C0781C108B9DF2688776F81AE94D9230C92ED570C9693C\"}" } } ] ``` #### Verification Object
KeyTypeDescriptionRequired
typeStringType of verification✅
versionStringStandard version✅
publicKeyStringPublic key for verifying data✅
transactionIdStringTransaction identifier✅
currentTypeString

Current type

  AC
  DC
✅
transactionBeginTransaction Event ObjectTransaction Begin event data✅ *
transactionEndTransaction Event ObjectTransaction End event data✅
{% hint style="info" %} **\*** `transactionBegin` is mandatory when `type=AC` {% endhint %} #### Transaction Event Object
KeyTypeDescriptionRequired
signedDataStringSigned transaction event data for verification✅
### Attachments Attachments such as entrance tickets and gift cards can be included. {% hint style="warning" %} This is a premium feature. To enable this option, please reach out to the ReceiptHero sales team. {% endhint %} ```json "attachments": [ { "type": "QRCODE", "kind": "TICKET", "title": "Here is your ticket!", "description": "Present this code at the entrance to maintain your access.", "data": "89942344234", "validUntil": "2024-09-10T00:00:00.000+02:00" } ] ```
KeyTypeDescriptionRequired
typeString

Type of attachment

BARCODE
QRCODE
✅
kindString

Kind represents the purpose of the attachment

TICKET
RETURN
VOUCHER
✅
titleStringTitle shown on top of the attachment✅
dataStringData encoded to the attachment according to the provided type✅
descriptionStringDescription providing more details on how this attachment is used
validUntilStringISO 8601 string with offset, representing the last moment the attachment is valid for use

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.receipthero.io/filetypes/receipthero-json/herojson-specification.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.