# Invoice metadata

Each invoice contains metadata, which is a customizable JSON object that can be tailored through the API during the creation of an invoice. Although it lacks a fixed schema, certain properties within the metadata can be interpreted by the UI.

This page provides an overview of these properties and explains how they are utilized within the BTCPay Server.

# Well-known properties

Property path Description
.orderId Refers to the order ID from an external system, such as an e-commerce platform like WooCommerce. This property is indexed, allowing for efficient invoice searches using the orderId.
.orderUrl Refers to a URL linking back to the order page of the external system. This link is displayed in the invoice details view.
.paymentRequestId In the invoice details view, a link is provided for navigating to the payment request page associated with the invoice.
.posData A custom JSON object that represents information displayed in the invoice details view.
.receiptData A custom JSON object that represents information displayed on the receipt page of an invoice.
.buyerName Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerEmail Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerAddress1 Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerAddress2 Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerCity Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerState Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerZip Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerCountry Visible in the invoice details view and in the BitPay API-compatible endpoints.
.buyerPhone Visible in the invoice details view and in the BitPay API-compatible endpoints.
.itemDesc When using the Point of Sale (except in keypad or cart view), this field is set to the item description of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view.
.itemCode When using the Point of Sale (except in keypad or cart view), this field is set to the item code of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view.
.physical Boolean value indicating whether this is a physical good; displayed in the invoice details view and in the BitPay API-compatible endpoints.
.taxIncluded Number representing the tax amount in the invoice currency. This information will appear in the invoice details view. During invoice creation, the value is automatically rounded to significant digits and ensured not to be greater than the invoice's price.

# Examples

Point of sale invoice (Product list view):

{
  "orderId": "pos-app_346KRC5BjXXXo8cRFKwTBmdR6ZJ4",
  "itemCode": "green tea",
  "itemDesc": "Green Tea",
  "orderUrl": "https://localhost:14142/apps/346KRC5BjXXXo8cRFKwTBmdR6ZJ4/pos",
  "receiptData": {
    "Title": "Green Tea",
    "Description": "Lovely, fresh and tender, Meng Ding Gan Lu ('sweet dew') is grown in the lush Meng Ding Mountains of the southwestern province of Sichuan where it has been cultivated for over a thousand years."
  }
}

Point of sale invoice (Cart view):

{
  "orderId": "pos-app_346KRC5BjXXXo8cRFKwTBmdR6ZJ4",
  "posData": {
    "tip": 0.48,
    "cart": [
      {
        "id": "pu erh",
        "count": 1,
        "image": "~/img/pos-sample/pu-erh.jpg",
        "price": {
          "type": 2,
          "value": 2,
          "formatted": "$2.00"
        },
        "title": "Pu Erh",
        "inventory": null
      },
      {
        "id": "rooibos",
        "count": 1,
        "image": "~/img/pos-sample/rooibos.jpg",
        "price": {
          "type": 2,
          "value": 1.2,
          "formatted": "$1.20"
        },
        "title": "Rooibos",
        "inventory": null
      }
    ],
    "total": 3.68,
    "subTotal": 3.2,
    "customAmount": 0,
    "discountAmount": 0,
    "discountPercentage": 0
  },
  "itemDesc": "Tea shop",
  "orderUrl": "https://localhost:14142/apps/346KRC5BjXXXo8cRFKwTBmdR6ZJ4/pos",
  "receiptData": {
    "Tip": "$0.48",
    "Cart": {
      "Pu Erh": "$2.00 x 1 = $2.00",
      "Rooibos": "$1.20 x 1 = $1.20"
    }
  }
}

Point of sale invoice (Keypad view):

{
  "orderId": "pos-app_346KRC5BjXXXo8cRFKwTBmdR6ZJ4",
  "posData": {
    "total": "12.00",
    "subTotal": "12.00"
  },
  "itemDesc": "Tea shop",
  "orderUrl": "https://localhost:14142/apps/346KRC5BjXXXo8cRFKwTBmdR6ZJ4/pos",
  "receiptData": {}
}