LIGHTNING-LISTINVOICES(7)

🌸 NAME 🌸

okay bestie, welcome to LIGHTNING-LISTINVOICES(7) — the manual page for listinvoices, aka the command for querying invoice status. no cap, this one is all about checking a specific invoice if it exists, or every invoice if you give it no argument, and it's honestly giving main character energy for your node's receipts. 💅

✨ SYNOPSIS ✨

here's the vibe check, literally:

listinvoices [label] [invstring] [payment_hash] [offer_id] [index
[start] [limit]]

💅 DESCRIPTION 💅

the listinvoices RPC command gets the status of a specific invoice, if it exists, or the status of all invoices if you give it no argument. it's that simple, bestie. ✨

lowkey important: only one of the query parameters can be used from label, invstring, payment_hash, or offer_id. pick one, not a whole combo meal. 🙈

query params, in cute list form:

• label (one of, optional) — a label used at the creation of the invoice to get a specific invoice. it's one of:
  • (string)
  • (integer)
• invstring (string, optional) — the string value to query a specific invoice.
• payment_hash (hex, optional) — a payment_hash of the invoice to get the details of a specific invoice.
• offer_id (string, optional) — a local offer_id the invoice was issued for, to get a specific invoice's details.
• index (string, optional) (one of "created", "updated") — if neither in_channel nor out_channel is specified, it controls ordering. the default is created. (added v23.08)
• start (u64, optional) — if index is specified, start may be specified to start from that value, which is generally returned from lightning-wait(7). (added v23.08)
• limit (u32, optional) — if index is specified, limit can be used to specify the maximum number of entries to return. (added v23.08)

👑 RETURN VALUE 👑

on success, an object containing invoices is returned. it's an array of objects, where each object contains:

• label (string) — unique label supplied at invoice creation.
• payment_hash (hash) — the hash of the payment_preimage which will prove payment.
• status (string) (one of "unpaid", "paid", "expired") — whether it's paid, unpaid or unpayable.
• expires_at (u64) — UNIX timestamp of when it will become / became unpayable.
• created_index (u64) — 1-based index indicating order this invoice was created in. (added v23.08)
• description (string, optional) — description used in the invoice.
• amount_msat (msat, optional) — the amount required to pay this invoice.
• bolt11 (string, optional) — the BOLT11 string (always present unless bolt12 is).
• bolt12 (string, optional) — the BOLT12 string (always present unless bolt11 is).
• local_offer_id (hash, optional) — the id of our offer which created this invoice.
• invreq_payer_note (string, optional) — the optional invreq_payer_note from invoice_request which created this invoice.
• updated_index (u64, optional) — 1-based index indicating order this invoice was changed (only present if it has changed since creation). (added v23.08)

if status is "paid", you also get these cuties:

• pay_index (u64) — unique incrementing index for this payment.
• amount_received_msat (msat) — the amount actually received (could be slightly greater than amount_msat, since clients may overpay).
• paid_at (u64) — UNIX timestamp of when it was paid.
• payment_preimage (secret) — proof of payment.
• paid_outpoint (object, optional) — outpoint this invoice was paid with. (added v23.11):
  • txid (txid) — ID of the transaction that paid the invoice. (added v23.11)
  • outnum (u32) — the 0-based output number of the transaction that paid the invoice. (added v23.11)

🦋 AUTHOR 🦋

the main character mainly responsible is Rusty Russell, rusty@rustcorp.com.au. slay. 💖

🎀 SEE ALSO 🎀

go read lightning-waitinvoice(7), lightning-delinvoice(7), and lightning-invoice(7). iykyk. ✨

🌈 RESOURCES 🌈

Main web site: https://github.com/ElementsProject/lightning

💀 EXAMPLES 💀

okay these examples are long but they ate, fr fr. copy them exactly:

Example 1:

Request:

$ lightning-cli listinvoices -k "label"="lbl_l21"

{
  "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
    }
  ]
}

Example 2:

Request:

$ lightning-cli listinvoices

{
  "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
    }
  ]
}

okay bestie, that's the whole page — footer era is Core Lightning v26.06.9 and LIGHTNING-LISTINVOICES(7), periodt. mwah 💋