{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "listinvoices",
  "title": "Command for querying invoice status",
  "description": [
    "The **listinvoices** RPC command gets the status of a specific invoice, if it exists, or the status of all invoices if given no argument.",
    "",
    "Only one of the query parameters can be used from *label*, *invstring*, *payment_hash*, or *offer_id*."
  ],
  "categories": [
    "readonly"
  ],
  "request": {
    "required": [],
    "additionalProperties": false,
    "properties": {
      "label": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          }
        ],
        "description": [
          "A label used a the creation of the invoice to get a specific invoice."
        ]
      },
      "invstring": {
        "type": "string",
        "description": [
          "The string value to query a specific invoice."
        ]
      },
      "payment_hash": {
        "type": "hex",
        "description": [
          "A payment_hash of the invoice to get the details of a specific invoice."
        ]
      },
      "offer_id": {
        "type": "string",
        "description": [
          "A local `offer_id` the invoice was issued for a specific invoice details."
        ]
      },
      "index": {
        "type": "string",
        "added": "v23.08",
        "enum": [
          "created",
          "updated"
        ],
        "description": [
          "If neither *in_channel* nor *out_channel* is specified, it controls ordering."
        ],
        "default": "`created`"
      },
      "start": {
        "type": "u64",
        "added": "v23.08",
        "description": [
          "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)."
        ]
      },
      "limit": {
        "type": "u32",
        "added": "v23.08",
        "description": [
          "If `index` is specified, `limit` can be used to specify the maximum number of entries to return."
        ]
      }
    },
    "dependentUpon": {
      "index": [
        "start",
        "limit"
      ]
    }
  },
  "response": {
    "required": [
      "invoices"
    ],
    "additionalProperties": false,
    "properties": {
      "invoices": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true,
          "required": [
            "label",
            "created_index",
            "payment_hash",
            "status",
            "expires_at"
          ],
          "properties": {
            "label": {
              "type": "string",
              "description": [
                "Unique label supplied at invoice creation."
              ]
            },
            "description": {
              "type": "string",
              "description": [
                "Description used in the invoice."
              ]
            },
            "payment_hash": {
              "type": "hash",
              "description": [
                "The hash of the *payment_preimage* which will prove payment."
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "unpaid",
                "paid",
                "expired"
              ],
              "description": [
                "Whether it's paid, unpaid or unpayable."
              ]
            },
            "expires_at": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when it will become / became unpayable."
              ]
            },
            "amount_msat": {
              "type": "msat",
              "description": [
                "The amount required to pay this invoice."
              ]
            },
            "bolt11": {
              "type": "string",
              "description": [
                "The BOLT11 string (always present unless *bolt12* is)."
              ]
            },
            "bolt12": {
              "type": "string",
              "description": [
                "The BOLT12 string (always present unless *bolt11* is)."
              ]
            },
            "local_offer_id": {
              "type": "hash",
              "description": [
                "The *id* of our offer which created this invoice."
              ]
            },
            "invreq_payer_note": {
              "type": "string",
              "description": [
                "The optional *invreq_payer_note* from invoice_request which created this invoice."
              ]
            },
            "created_index": {
              "type": "u64",
              "added": "v23.08",
              "description": [
                "1-based index indicating order this invoice was created in."
              ]
            },
            "updated_index": {
              "type": "u64",
              "added": "v23.08",
              "description": [
                "1-based index indicating order this invoice was changed (only present if it has changed since creation)."
              ]
            }
          },
          "allOf": [
            {
              "if": {
                "additionalProperties": true,
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "paid"
                    ]
                  }
                }
              },
              "then": {
                "additionalProperties": false,
                "required": [
                  "pay_index",
                  "amount_received_msat",
                  "paid_at",
                  "payment_preimage"
                ],
                "properties": {
                  "label": {},
                  "description": {},
                  "payment_hash": {},
                  "status": {},
                  "msatoshi": {},
                  "amount_msat": {},
                  "bolt11": {},
                  "bolt12": {},
                  "local_offer_id": {},
                  "invreq_payer_note": {},
                  "expires_at": {},
                  "created_index": {},
                  "updated_index": {},
                  "pay_index": {
                    "type": "u64",
                    "description": [
                      "Unique incrementing index for this payment."
                    ]
                  },
                  "amount_received_msat": {
                    "type": "msat",
                    "description": [
                      "The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
                    ]
                  },
                  "paid_at": {
                    "type": "u64",
                    "description": [
                      "UNIX timestamp of when it was paid."
                    ]
                  },
                  "paid_outpoint": {
                    "type": "object",
                    "description": [
                      "Outpoint this invoice was paid with."
                    ],
                    "added": "v23.11",
                    "additionalProperties": false,
                    "required": [
                      "txid",
                      "outnum"
                    ],
                    "properties": {
                      "txid": {
                        "added": "v23.11",
                        "type": "txid",
                        "description": [
                          "ID of the transaction that paid the invoice."
                        ]
                      },
                      "outnum": {
                        "added": "v23.11",
                        "type": "u32",
                        "description": [
                          "The 0-based output number of the transaction that paid the invoice."
                        ]
                      }
                    }
                  },
                  "payment_preimage": {
                    "type": "secret",
                    "description": [
                      "Proof of payment."
                    ]
                  }
                }
              },
              "else": {
                "additionalProperties": false,
                "properties": {
                  "label": {},
                  "description": {},
                  "payment_hash": {},
                  "status": {},
                  "msatoshi": {},
                  "amount_msat": {},
                  "bolt11": {},
                  "bolt12": {},
                  "local_offer_id": {},
                  "invreq_payer_note": {},
                  "created_index": {},
                  "updated_index": {},
                  "expires_at": {}
                }
              }
            }
          ]
        }
      }
    }
  },
  "author": [
    "Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
  ],
  "see_also": [
    "lightning-waitinvoice(7)",
    "lightning-delinvoice(7)",
    "lightning-invoice(7)"
  ],
  "resources": [
    "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
  ],
  "examples": [
    {
      "request": {
        "id": "example:listinvoices#1",
        "method": "listinvoices",
        "params": {
          "label": "lbl_l21"
        }
      },
      "response": {
        "invoices": [
          {
            "label": "lbl_l21",
            "bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
            "payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
            "status": "paid",
            "pay_index": 4,
            "amount_received_msat": 400000,
            "paid_at": 1738500000,
            "payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
            "description": "l21 description",
            "expires_at": 1739000000,
            "created_index": 2,
            "updated_index": 4
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:listinvoices#2",
        "method": "listinvoices",
        "params": {}
      },
      "response": {
        "invoices": [
          {
            "label": "lbl balance l1 to l2",
            "bolt11": "lnbcrt222n1pnt3005720bolt114000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
            "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
            "amount_msat": 500000000,
            "status": "paid",
            "pay_index": 1,
            "amount_received_msat": 500000000,
            "paid_at": 1738500000,
            "payment_preimage": "paymentpreimgdp1010101010101010101010101010101010101010101010101",
            "description": "description send some sats l1 to l2",
            "expires_at": 1739000000,
            "created_index": 1,
            "updated_index": 1
          },
          {
            "label": "lbl_l21",
            "bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
            "payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
            "status": "paid",
            "pay_index": 4,
            "amount_received_msat": 400000,
            "paid_at": 1738510000,
            "payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
            "description": "l21 description",
            "expires_at": 1739010000,
            "created_index": 2,
            "updated_index": 4
          },
          {
            "label": "lbl_l22",
            "bolt11": "lnbcrt100n1pnt2bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000",
            "payment_hash": "paymenthashinvl0220022002200220022002200220022002200220022002200",
            "amount_msat": 200000,
            "status": "unpaid",
            "description": "l22 description",
            "expires_at": 1739020000,
            "created_index": 3,
            "paid_at": 1738520000
          },
          {
            "label": "label inv_l24",
            "bolt11": "lnbcrt100n1pnt2bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000",
            "payment_hash": "paymenthashinvl0240024002400240024002400240024002400240024002400",
            "amount_msat": 123000,
            "status": "unpaid",
            "description": "description inv_l24",
            "expires_at": 1739030000,
            "created_index": 4,
            "paid_at": 1738530000
          },
          {
            "label": "label inv_l25",
            "bolt11": "lnbcrt100n1pnt2bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000",
            "payment_hash": "paymenthashinvl0250025002500250025002500250025002500250025002500",
            "amount_msat": 124000,
            "status": "unpaid",
            "description": "description inv_l25",
            "expires_at": 1739040000,
            "created_index": 5,
            "paid_at": 1738540000
          }
        ]
      }
    }
  ]
}
