# 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](https://developer.anybill.de/vendor_api/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`.

> **Tip: 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):
``` json
{
  "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.

``` json
{
  "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:
``` json
{
  "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`).

> **Tip: Example**
> Bill A:
> ```json
> {
>   "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: 
> ```json
> {
>   "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
>                   }
>                },
>                ...
>             }
>          ]
>       },
>       ...
>    }
> }
> ```

> **Warning: 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](https://developer.anybill.de/images/predefined_sections.png). 

### 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.

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

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

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

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

::: details divider
A horizontal separator line without further properties.
``` json
{
   "sequenceNumber": 2,
   "customSectionId": "NameId",
   "type": "divider"
}
```
:::

### Custom section example
``` json
"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"
            }
      ]
   }
]
```