core-lightning/doc/lightning-listinvoices.7

.TH "LIGHTNING-LISTINVOICES" "7" "" "" "lightning-listinvoices"
.SH NAME
lightning-listinvoices - Command for querying invoice status
.SH SYNOPSIS

\fBlistinvoices\fR [\fIlabel\fR] [\fIinvstring\fR] [\fIpayment_hash\fR] [\fIoffer_id\fR]

.SH DESCRIPTION

The \fBlistinvoices\fR RPC command gets the status of a specific invoice,
if it exists, or the status of all invoices if given no argument\.


A specific invoice can be queried by providing either the \fBlabel\fR
provided when creating the invoice, the \fBinvstring\fR string representing
the invoice, the \fBpayment_hash\fR of the invoice, or the local \fBoffer_id\fR
this invoice was issued for\. Only one of the query parameters can be used at once\.

.SH RETURN VALUE

On success, an object containing \fBinvoices\fR is returned\.  It is an array of objects, where each object contains:

.RS
.IP \[bu]
\fBlabel\fR (string): unique label supplied at invoice creation
.IP \[bu]
\fBdescription\fR (string): description used in the invoice
.IP \[bu]
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
.IP \[bu]
\fBstatus\fR (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
.IP \[bu]
\fBexpires_at\fR (u64): UNIX timestamp of when it will become / became unpayable
.IP \[bu]
\fBamount_msat\fR (msat, optional): the amount required to pay this invoice
.IP \[bu]
\fBbolt11\fR (string, optional): the BOLT11 string (always present unless \fIbolt12\fR is)
.IP \[bu]
\fBbolt12\fR (string, optional): the BOLT12 string (always present unless \fIbolt11\fR is)
.IP \[bu]
\fBlocal_offer_id\fR (hex, optional): the \fIid\fR of our offer which created this invoice (\fBexperimental-offers\fR only)\. (always 64 characters)
.IP \[bu]
\fBpayer_note\fR (string, optional): the optional \fIpayer_note\fR from invoice_request which created this invoice (\fBexperimental-offers\fR only)\.

.RE

If \fBstatus\fR is "paid":

.RS
.IP \[bu]
\fBpay_index\fR (u64): Unique incrementing index for this payment
.IP \[bu]
\fBamount_received_msat\fR (msat): the amount actually received (could be slightly greater than \fIamount_msat\fR, since clients may overpay)
.IP \[bu]
\fBpaid_at\fR (u64): UNIX timestamp of when it was paid
.IP \[bu]
\fBpayment_preimage\fR (hex): proof of payment (always 64 characters)

.RE
.SH AUTHOR

Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.

.SH SEE ALSO

\fBlightning-waitinvoice\fR(7), \fBlightning-delinvoice\fR(7), \fBlightning-invoice\fR(7)\.

.SH RESOURCES

Main web site: \fIhttps://github.com/ElementsProject/lightning\fR

\" SHA256STAMP:37d1f6f0b6160b9aa4944f730bec6b04469a9f9a293b59cf8f6663d37073da9c