# 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": {}
}