Bill Examples

Complete payload examples for the cases that are hardest to get right. They build on the structures described in the Bill Data Model.

Discounts

A discount can either be set to each line item individually or to the whole receipt.

Discount for individual line items

To discount a single line item, fill the discounts array in the extension:anybill of the line. Each applied discount references a definition (see below) via its discountId. If multiple discounts are applied to one line item, the sequenceNumber can be set to show the consumer how the final price is composed.

A discounted line uses the following amounts:

• fullAmountInclVat – the gross line total after all discounts.
• extension:anybill.fullAmountInclVatBeforeDiscounts – the gross line total before any discount.
• item.extension:anybill.pricePerUnitBeforeDiscounts – the original gross price per unit before discounts.

Each discount vatAmounts.percentage must also be present in the line's vatAmounts.

Sign of fullAmountInclVat

Both positive and negative values are accepted for a discount's fullAmountInclVat – the sign only affects how the amount is rendered on the (PDF) receipt. We recommend using negative values for discount amounts.

Example (one line item with a 20 % discount):

{
  "text": "Baumwoll T-Shirt",
  "vatAmounts": [
    { "percentage": 19.0, "inclVat": 16.0, "exclVat": 13.45, "vat": 2.55 }
  ],
  "fullAmountInclVat": 16.0,
  "item": {
    "quantity": 1.0,
    "pricePerUnit": 16.0,
    "extension:anybill": {
      "pricePerUnitBeforeDiscounts": 20.0
    }
  },
  "extension:anybill": {
    "sequenceNumber": 0,
    "fullAmountInclVatBeforeDiscounts": 20.0,
    "discounts": [
      {
        "sequenceNumber": 0,
        "discountId": "DISC_TSHIRT_20",
        "vatAmounts": [
          { "percentage": 19.0, "inclVat": 4.0, "exclVat": 3.36, "vat": 0.64 }
        ],
        "fullAmountInclVat": -4.0
      }
    ]
  }
}

To describe an applied discount, add a definition to data.extension:anybill.discounts and reference it by setting the line discount's discountId to the definition's id (the id is an arbitrary reference string and is not shown to the customer). If the same discount applies to multiple line items, define it once and reference it from each line. The definition's type is one of Percentage, Monetary, MonetaryReplacement or None, and value holds the percentage (e.g. 20) or the monetary amount (e.g. 5). fullAmountInclVatBeforeDiscounts on the data extension is the gross total of the whole receipt before any discounts.

{
  "extension:anybill": {
    "fullAmountInclVatBeforeDiscounts": 40.0,
    "discounts": [
      {
        "id": "DISC_TSHIRT_20",
        "name": "20 % Rabatt T-Shirt",
        "value": 20.0,
        "type": "Percentage",
        "vatAmounts": [
          { "percentage": 19.0, "inclVat": 4.0, "exclVat": 3.36, "vat": 0.64 }
        ],
        "fullAmountInclVat": -4.0
      },
      {
        "id": "DISC_CAP_5EUR",
        "name": "5 € Rabatt Cap",
        "value": 5.0,
        "type": "Monetary",
        "vatAmounts": [
          { "percentage": 19.0, "inclVat": 5.0, "exclVat": 4.2, "vat": 0.8 }
        ],
        "fullAmountInclVat": -5.0
      }
    ]
  }
}

Discount for the whole receipt

To add a discount that is applied to the whole receipt the discount line can be used. Multiple discount lines can be used for different discounts.
To enhance the information from which line items the discount is made up the relatedLines property can be used. Either use it on the vatAmounts to link the to the line item by the sequenceNumber or set all lines on the root.

Example:

{
  "text": "Wochenendrabatt 3 %",
  "additionalText": "3 % Rabatt am Wochenende",
  "vatAmounts": [
    {
      "percentage": 7,
      "inclVat": 0.09,
      "exclVat": 0.08411,
      "vat": 0.00589,
      "relatedLines": [
        0
      ]
    },
    {
      "percentage": 19,
      "inclVat": 0.08,
      "exclVat": 0.06723,
      "vat": 0.01277,
      "relatedLines": [
        2
      ]
    }
  ],
  "fullAmountInclVat": 0.17,
  "relatedLines": null,
  "extension:anybill": {
    "sequenceNumber": 3,
    "type": "discount"
  },
  ...
}

Returning a line item

If you want to return a bills line item the following steps are necessary:

• Given an existing receipt A with a line item A1.
• Create a new receipt B with an extra line item B1 which represents the returned line item A1.
• Set the lineReturnReference object in the anybill extension of line item B1: returnCodeReference takes the value of misc.extension:anybill.returnBarcode of receipt A, originalReceiptIdReference optionally takes the anybill receipt id (billId) of receipt A.
• Save receipt B.

A line item is then displayed as "returned" in receipt B.

The return barcode of receipt A is printed on the receipt so that the cashier can scan it when the customer returns the goods. It requires returnBarcodeType (Ean8, Ean13, Text, Qr, Barcode, Code128ABarcode, Code128BBarcode or Code128CBarcode).

Example

Bill A:

{
  "storeId": "8192538C-CC23-488B-B35B-0F16BE1B8F43",
  "bill": {
     "head": {
        "date": "2020-06-20T13:00:00+00:00",
        ...
     },
     "data": {
        "lines": [
           {
              "text": "A1",
              "item": { "quantity": 1, ... },
              "fullAmountInclVat": 1.00,
              ...
           },
           {
              "text": "A2",
              "item": { "quantity": 3, ... },
              ...
           }
        ]
     },
     "misc": {
        "extension:anybill": {
           "returnBarcode": "123",
           "returnBarcodeType": "Text",
           ...
        },
        ...
     },
     ...
   } 
}

Bill B:

{
  "storeId": "8192538C-CC23-488B-B35B-0F16BE1B8F43",
   "bill": {
      "head": {
         "date": "2020-06-20T15:00:00+00:00",
         ...
      },
      "data": {
         "lines": [
            {
               "text": "B1",
               "item": { "quantity": 1, ... },
               "fullAmountInclVat": -1.00,
               "extension:anybill": {
                  "sequenceNumber": 0,
                  "lineReturnReference": {
                     "returnCodeReference": "123", // see returnBarcode of Receipt A
                     "originalReceiptIdReference": "5e952ea6-167d-4001-95d9-a759204c2943" // optional: billId of Receipt A
                  }
               },
               ...
            }
         ]
      },
      ...
   }
}

Deprecated return fields

The line extension properties returnBarcodeReference and isReturn are deprecated. returnBarcodeReference maps to lineReturnReference.returnCodeReference; isReturn is implied by the presence of lineReturnReference.

Custom sections

Custom sections allow you to insert your own attributes between the defined areas in order to individualize the receipt and display the necessary information.

A custom section can be inserted either before or after a defined area, contains a title and a list of data which are displayed in the given order by the sequenceNumber. The title will not be displayed on pdf. May be used in digital display formats.

The customSectionId can be used if it should be needed again later via the SDK. Must be unique across all customSections.

Areas

The receipt is generally divided into the following areas:

• Head
• Lines
• PaymentDetails
• VatDetails
• AdditionalData
• Buyer
• FooterText
• TseInformation
• AfterSalesCoupons
• HospitalityInformation

A receipt with the marked sections can be downloaded here.

Types

Currently, data of type text, keyValue, barcode, qrCode or divider can be added to a custom section. type is mandatory for every entry; text, key/value and value are limited to 1024 (text) respectively 128 characters.

text

{
   "sequenceNumber": 0,
   "customSectionId": "NameId",
   "type": "text",
   "text": "text message",
   "alignment": "Left|Center|Right"
}

keyValue

{
   "sequenceNumber": 1,
   "customSectionId": "NameId",
   "type": "keyValue",
   "key": "LoyaltyCard number:",
   "value": "123456789"
}

barcode

{
   "sequenceNumber": 0,
   "customSectionId": "NameId",
   "type": "barcode",
   "barcodeType": "Barcode|Code128ABarcode|Code128BBarcode|Code128CBarcode",
   "value": "Value of the barcode"
}

qrCode

{
   "sequenceNumber": 0,
   "customSectionId": "NameId",
   "type": "qrCode",
   "value": "Value of the qrCode"
}

divider

A horizontal separator line without further properties.

{
   "sequenceNumber": 2,
   "customSectionId": "NameId",
   "type": "divider"
}

Custom section example

"customSections": [
   {
      "position": "Before",
      "section": "Head",
      "title": "Title of the custom head section",
      "data": [
            {
               "sequenceNumber": 0,
               "type": "Text",
               "text": "Before Head text"
            },
            {
               "sequenceNumber": 1,
               "type": "KeyValue",
               "key": "LoyaltyCard number:",
               "value": "123456789"
            }
      ]
   },
   {
      "position": "After",
      "section": "VatDetails",
      "title": "Title of the custom VAT details section",
      "data": [
            {
               "sequenceNumber": 0,
               "type": "barcode",
               "barcodeType": "Code128ABarcode",
               "value": "Value of the barcode"
            },
            {
               "sequenceNumber": 1,
               "type": "qrCode",
               "value": "Value of the qrCode"
            }
      ]
   }
]