listinvoices -- Command for querying invoice status

SYNOPSIS

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 given no argument.

Only one of the query parameters can be used from label, invstring, payment_hash, or offer_id.

label (one of, optional): A label used a the creation of the invoice to get a specific invoice.:
- (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 a specific invoice 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 is 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":

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

Rusty Russell 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

EXAMPLES

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