home | help 
LIGHTNING-LISTINVOICES(7)			       LIGHTNING-LISTINVOICES(7)

NAME
     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, pay-
     ment_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 in-
	voice.
     *	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  de-
	fault 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 spec-
	ify 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 un-
	payable.
     *	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 in-
	voice 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 (se-
     cret): 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
	 }
       ]
     }

Core Lightning v26.06.1 			       LIGHTNING-LISTINVOICES(7)
home | help