# Receipt Data Elements ## In This Guide * [Receipts API Integration Guide](/receipts/receipts-integration-guide.html) — authentication, request/response flow, error handling, and best practices. * [Request Field Reference](/receipts/request-reference.html) — field-by-field usage notes for headers, discounts, loyalty, tenders, taxes, items, custom fields, and more. * **Receipt Data Elements** — how request fields map to sections of a rendered receipt (orders, returns, totals, deposits, payment history, and more). * [Point of Sale UI Guidelines](/receipts/pos-ui-guidelines.html) — recommended configuration options and UI flow. * [Printed Offers](/receipts/printed-offers.html) — for merchants whose package includes printed offers. * [SMS Receipts](/receipts/sms-receipts.html) — for merchants whose package includes SMS delivery. * [Integration Testing Checklist](/receipts/testing-checklist.html) — validate your integration before launch. ## Request Message All the JSON elements referenced in the [Receipts API](/receipts-api.html) reference are expected unless otherwise indicated below or a written waiver is obtained from flexEngage. **DO NOT send non-required elements that you do not use.** ***MAKE SURE THAT EVERYTHING THAT APPEARS ON THE PAPER RECEIPT IS SENT.*** # Anatomy of a Digital Receipt flexEngage will work with the merchant to create a suitable receipt template based on their requirements. Below is a sample email receipt that has been annotated followed by a table that identifies the JSON elements used for the annotated data. There are also expanded views of specific sections following this high level sample. ## Figure 1: Sample Email Receipt Template ![Sample Email Receipt Template](/receipts/images/sample-receipt-template-part1.png) ![Sample Email Receipt Template](/receipts/images/sample-receipt-template-part2.png) ![Sample Email Receipt Template](/receipts/images/sample-receipt-template-part3.png) ![Sample Email Receipt Template](/receipts/images/sample-receipt-template-part4.png) ## Sample Email Receipt Annotation Key The table below identifies the Merchant (Web) Portal and OpenAPI elements used in the annotated email receipt sample (above) and the PDF receipt sample (below).
1Email Subject Line from Merchant Portal2Email Sender Name and Sender Email Address from Merchant Portal
3Email Header from Merchant Portal4Survey from Merchant Portal
5Logo from Merchant Portal6See "Store Information" below
7ReceiptHeader8See "Receipt Transaction Header" - below
9See "Item Information" below13See "Order Information" below
14See "Return Information" - below15See "Receipt Summary Information" below
16See "Tender Information" below17See "Deposit Information" below
18See "Payment History" below19See "Sold To Information" below
20See "Delivery Pickup Information" below21See "Terms and Conditions" below
22See "Transaction Signature' below23Corporate Social Media Links from Merchant Portal
24additionalInfo1 additionalInfo2 additionalInfo3 additionalInfo4 additionalInfo525Receipt Footer from Merchant Portal
26Barcode Graphic generated based on: barcodeType barcodeNumber27Marketing Campaign Content from Merchant Portal
28Email Footer from Merchant Portal29Static content provided by flexEngage
## Store Information Below is the Store Information on the email receipt. ![Store Information on the email receipt](/receipts/images/anatomy-store-information.png) ```json "store": { "id": "001", "name": "flexEngage Retail Store", "address": { "typeCode": null, "addressLine1": "14 E Washington Street", "city": "Orlando", "territory": "FL", "postalCode": "32584", "country": { "value": "US", "code": "US" }, "postalCodeExtension": null }, "telephone": { "areaCode": "407", "localNumber": "60FLEX8" } } ``` ## Receipt Transaction Header Below the Receipt Transaction Header on the email receipt. ![Receipt Transaction Header on the email receipt](/receipts/images/anatomy-receipt-transaction-header.png)
8A 
"transactionNumber": "88888",
"receiptDateTime": "2016-05-13T11:40:16-07:00",
8B 
"revision": {
  "number": "999",
  "dateTime": "2016-05-13T11:40:16-07:00"
},
8C 
"workstation": {
  "id": "090",
  "operator": "Jbob",
  "associate": "Sam",
  "store": {
    "id": "333",
    ….
  }
  ….
}
8D 
"relatedTransactionReference": {
  "store": "111",
  "register": "020",
  "transactionNumber": "98765",
  "reasonCode": "R555",
  "reason": "Detailed Reason Here"
},
8E 
"loyalty": {
  "number": "12345",
  "customerName": "Joe Customer",
  "expirationDateTime": "2017-05-13",
  "balance": 9999,
  "misc": "Point Earned this Purchase: 500"
},
## Item Information Below the Item Information on the email receipt. ![Item Information on the email receipt](/receipts/images/anatomy-item-information.png) ```json "items": [ { "name": "LIVING ROOM SET", "description": null, "classCode": null, "sku": "20170220001", "upc": "20170220001", "price": 2049, "total": 1499, "priceNotation": "T", "quantity": { "value": 1, "units": 1, "unitOfMeasureCode": "Each" }, "discounts": [ { "amount": -550.97, "name": "Sale" } ], "miscInfo": "Reg: $2,049.00 Sale: $1,499.00 You Saved: $550.97\nflexEngage In-Home Delivery\n(Assembly Included)\nUsually delivers in 3 to 4 weeks", "supportingDocuments": { "Review 1": {"name": "Write a review", "url": "https://www.flexEngage.com/review"}, "WARRANTY1": {"name": "Warranty Information", "url": "https://www.flexEngage.com/warranty-information"} } } ] ``` See the [Request Field Reference](/receipts/request-reference.html#item-information) for more on item pricing, discounts, and price notations. ## Order Information Below is the Order Information on the email receipt. ![Order Information on the email receipt](/receipts/images/anatomy-order-information.png)
13A 
"orders": [
  {
    "number": "298323",
    "action": "Create",
    "barcodeNumber": "2342342",
    "barcodeType": "Code128",
    "description": "Description of Order",
13B 
    "items": [
      {
        "name": "Backordered Item",
        "description": "Prod Description Text",
        "classCode": null,
        "sku": "00000001",
        "upc": "00000001",
        "price": 1.0,
        "total": 1.0,
        "priceNotation": "TP",
        "quantity": { "value": 2, "units": 2, "unitOfMeasureCode": "EACH" },
        "discounts": [
          { "amount": -1.0, "name": "BOGO Free" }
        ],
        "miscInfo": "This is a cool product"
      }
    ]
13C 
    "totalAmount": 1.0,
    "taxes": [
      { "description": "Sales Tax", "percent": 0.0, "taxableAmount": 1.0, "amount": 1.0, "taxTypeCode": "Sales" }
    ],
    "fees": [
      { "amount": 1.0, "description": "Delivery Charge" }
    ],
13D 
    "deposits": [
      { "accountNumber": "Account Number", "amount": 1.0, "balanceDue": 1.0 }
    ],
13E 
    "paymentSchedules": [
      { "description": "First Payment", "amountDue": 1.0, "dueDate": "2016-12-12" },
      { "description": "Second Payment", "amountDue": 2.0, "dueDate": "2016-12-15" }
    ],
13F 
    "soldTo": {
      "address": {
        "typeCode": null,
        "addressLine1": "14 Main Street",
        "addressLine2": "Floor 2",
        "city": "Orlando",
        "territory": "FL",
        "postalCode": "32054",
        "country": { "value": "Country", "code": "US" },
        "postalCodeExtension": "0000"
      },
      "customerName": "Joe Customer",
      "customerNumber": "123643",
      "telephone1": { "areaCode": "212", "localNumber": "3334444" },
      "telephone2": { "areaCode": "555", "localNumber": "2224444" }
    },
13G 
    "deliveryPickup": {
      "address": {
        "typeCode": null,
        "addressLine1": "555 South Street",
        "city": "Somewhere",
        "territory": "FL",
        "postalCode": "34444",
        "country": { "value": "Country", "code": "US" },
        "postalCodeExtension": "1234"
      },
      "instructions": "Delivery-Pickup Instructions",
      "dateTime": "2014-01-01"
    }
`action` describes what kind of order event this is — valid values include `Create`, `Modify`, `Cancel`, `Payment`, `Shipment`, `Pickup`, `Return`, `Notify`, and `Other`. ## Return Information Below is the Return Information on the email receipt. ![Return Information on the email receipt](/receipts/images/anatomy-return-information.png)
14A 
"returns": [
  {
    "originalStoreNumber": "777",
    "originalRegister": "030",
    "originalTransactionNumber": "111111111",
    ….
  }
],
14B 
"items": [
  {
    "name": "Returned Item",
    "description": "Returned Item Description",
    "sku": "222222",
    "upc": "222222",
    "price": -10.0,
    "total": -10.0,
    "priceNotation": "TP",
    "quantity": { "value": 1, "units": 1, "unitOfMeasureCode": "EACH" },
    "supportingDocuments": {
      "return1": {"name": "return1 Link", "url": "http://www.example.com/return1"},
      "return2": {"name": "return2 Link", "url": "http://www.example.com/return2"}
    },
    "discounts": [
      { "amount": 3.0, "name": "$3 Off" }
    ]
  }
]
## Receipt Summary Information Below is the Receipt Summary Information on the email receipt. ![Receipt Summary Information on the email receipt](/receipts/images/anatomy-receipt-summary.png) ```json "grossAmount": 1499, "discounts": [ { "amount": -1.0, "name": "Discount Name" } ], "netAmount": 1618.99, "taxes": [ { "description": null, "percent": 0.06, "taxableAmount": 1499, "amount": 89.94, "taxTypeCode": "Sales" }, { "description": "County Tax", "percent": 0.045, "taxableAmount": 1000, "amount": 45, "taxTypeCode": "Sales" } ], "grandAmount": 1708.93, "tip": 1.0, "serviceCharge": 1.0, "fees": [ { "amount": 119.99, "description": "In-Home Delivery" }, { "amount": 20.99, "description": "Installation Fee" } ] ``` ## Tender Information *Below is the Tender Information on the email receipt.* ![Tender Information on the email receipt](/receipts/images/anatomy-tender-information.png)
16A 
"tenders": [
  {
    "tenderTypeCode": "Cash",
    "dateTime": null,
    "amount": 1800,
    "creditDebit": null,
    "miscInfo": null,
    "currency": "USD"
  },
16B 
  {
    "tenderTypeCode": "GiftCard",
    "dateTime": null,
    "amount": 250,
    "giftCard": {
      "accountNumber": "*********3222",
      "balance": 0,
      "authNumber": "1234556"
    },
    "miscInfo": null,
    "emv": null,
    "currency": "USD"
  },
16C 
  {
    "tenderTypeCode": "CreditDebit",
    "dateTime": "2014-01-01T00:00:00+05:00",
    "amount": 100,
    "creditDebit": {
      "first6Digits": null,
      "last4Digits": "6332",
      "typeCode": "VISA"
    },
    "authorizationCode": "98765",
    "miscInfo": null,
    "emv": {
      "aid": "A0000000031010",
      "appLabel": "VISA DEBIT",
      "appPreferredName": null,
      "additionalAttributes": {
        "CARD ENTRY MODE": "Chip Read",
        "EMV TAG 5F2A": "0840",
        "EMV TAG 8A": "00",
        "EMV TAG 95": "0000008000",
        "EMV TAG 9B": "E800",
        "EMV TAG 9F10": "06O10A03600000",
        "EMV TAG 9F34": "1E0300",
        "EMV MODE": "ISSUER",
        "EMV CVM": "SIGNATURE",
        "EMV CHIP INDICATOR": "CONTACT"
      }
    },
    "currency": "USD"
  }
]
16D 
"tenderApplied": 1800,
"changeDue": 91.07,
## Deposit Information *Below is the Deposit Information on the email receipt.* ![Deposit Information on the email receipt](/receipts/images/anatomy-deposit-information.png) ```json "deposit": { "accountNumber": "555555", "amount": 36.30, "balanceDue": 40.0 } ``` ## Payment History *Below is the Payment History on the email receipt.* ![Payment History on the email receipt](/receipts/images/anatomy-payment-history.png) ```json "tenderHistory": [ { "tenderTypeCode": "GiftCard", "dateTime": "2016-05-13T00:00:00+05:00", "amount": 10.00 }, { "tenderTypeCode": "CreditDebit", "dateTime": "2016-05-13T00:00:00+05:00", "amount": 26.30, "creditDebit": { "first6Digits": "000000", "last4Digits": "0000", "typeCode": "Visa" } } ] ``` ## Sold To Information *Below is the Sold To Information on the email receipt.* ![Sold To Information on the email receipt](/receipts/images/anatomy-sold-to-information.png) ```json "soldTo": { "address": { "typeCode": null, "addressLine1": "22 Main Street", "city": "Orlando", "territory": "FL", "postalCode": "34734", "country": { "value": "US", "code": "US" }, "postalCodeExtension": null }, "customerName": "Joe", "customerNumber": null, "telephone1": { "areaCode": "321", "localNumber": "0000000" } } ``` ## Delivery Pick-up Information Below is the Delivery Pick-up Information on the email receipt. ![Delivery Pick-up Information on the email receipt](/receipts/images/anatomy-delivery-pickup-information.png) ```json "deliveryPickup": { "address": { "typeCode": null, "addressLine1": "22 Elm Street", "addressLine2": null, "addressLine3": null, "city": "New York", "territory": "NY", "postalCode": "10009", "country": { "value": "Country", "code": "US" }, "postalCodeExtension": null }, "instructions": "These are the delivery pickup instructions", "dateTime": "2016-01-06" } ``` ## Terms and Conditions *Below is the Terms and Conditions on the email receipt.* ![Terms and Conditions on the email receipt](/receipts/images/anatomy-terms-and-conditions.png) ```json "terms": [ { "signature": { "base64Image": "iVBORw0KGgoAAA…..", "imageMimeType": "image/png", "dateTime": "2016-05-13", "text": null }, "description": "These are the terms you just agreed to\nI have read and agree...", "supportingDocuments": null } ] ``` ## Transaction Signature *Below is the Transaction Signature on the email receipt.* ![Transaction Signature on the email receipt](/receipts/images/anatomy-transaction-signature.png) ```json "signature": { "base64Image": "iVBORw0KGgoAAAANSU…..", "imageMimeType": "image/png", "dateTime": "2016-05-13", "text": "This is the transaction signature" } ```