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

NAME
     fetchinvoice -- Command for fetch an invoice for an offer

SYNOPSIS
     fetchinvoice  offer  [amount_msat]  [quantity] [recurrence_counter] [recur-
     rence_start]  [recurrence_label]  [timeout]  [payer_note]	[payer_metadata]
     [bip353]

DESCRIPTION
     The  fetchinvoice RPC command contacts the issuer of an offer to get an ac-
     tual invoice that can be paid. It highlights any changes between the  offer
     and the returned invoice.

     If  fetchinvoice-noconnect  is  not  specified in the configuation, it will
     connect to the destination in the (currently common!) case where it  cannot
     find a route which supports option_onion_messages.

     *	offer (string): Offer string to get an actual invoice that can be paid.
     *	amount_msat  (msat, optional): Required if the offer does not specify an
	amount at all, otherwise it is optional (but presumably if you set it to
	less than the offer, you will get an error from the issuer).
     *	quantity (u64, optional): Required if the offer specifies  quantity_max,
	otherwise it is not allowed.
     *	recurrence_counter  (u64, optional): Required if the offer specifies re-
	currence, otherwise it is not allowed. recurrence_counter  should  first
	be  set to 0, and incremented for each successive invoice in a given se-
	ries.
     *	recurrence_start (number, optional): Indicates	what  period  number  to
	start at (usually 0).
     *	recurrence_label  (string,  optional): Required if recurrence_counter is
	set, and otherwise is not allowed. It must be the same as prior fetchin-
	voice calls for the same recurrence, as it is  used  to  link  them  to-
	gether.
     *	timeout  (number, optional): If we don't get a reply before this we fail
	(default, 60 seconds).
     *	payer_note (string, optional): To ask  the  issuer  to	include  in  the
	fetched invoice.
     *	payer_metadata	(string,  optional): Derive the payer_id from the speci-
	fied payer_metadata. Please be sure that payer_metdata can  not  be  de-
	rived by anyone, so put some secret into it. (added v24.11)
     *	bip353 (string, optional): BIP353 string (optionally with a?) indicating
	where we fetched the offer from (added v25.02)

RETURN VALUE
     On success, an object is returned, containing:

     *	invoice (string): The BOLT12 invoice we fetched.
     *	changes (object): Summary of changes from offer.:
	*  description_appended (string, optional): Extra characters appended to
	   the description field.
	*  description	(string,  optional):  A  completely replaced description
	   field.
	*  vendor_removed (string, optional): The vendor from the  offer,  which
	   is missing in the invoice.
	*  vendor (string, optional): A completely replaced vendor field.
	*  amount_msat (msat, optional): The amount, if different from the offer
	   amount multiplied by any quantity (or the offer had no amount, or was
	   not in BTC).
     *	next_period  (object, optional): Only for recurring invoices if the next
	period is under the recurrence_limit.:
	*  counter (u64): The index of the next period to fetchinvoice.
	*  starttime (u64): UNIX timestamp that the next period starts.
	*  endtime (u64): UNIX timestamp that the next period ends.
	*  paywindow_start (u64): UNIX timestamp of the earliest time  that  the
	   next invoice can be fetched.
	*  paywindow_end  (u64): UNIX timestamp of the latest time that the next
	   invoice can be fetched.

ERRORS
     The following error codes may occur:

     *	-1: Catchall nonspecific error.
     *	1002: Offer has expired.
     *	1003: Cannot find a route to the node making the offer.
     *	1004: The node making the offer returned an error message.
     *	1005: We timed out trying to fetch an invoice.

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-sendinvoice(7), lightning-xpay(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli fetchinvoice -k "offer"="lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000" "payer_note"="Thanks for the fish!"

     {
       "id": "example:fetchinvoice#1",
       "method": "fetchinvoice",
       "params": {
	 "offer": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
	 "payer_note": "Thanks for the fish!"
       }
     }

     Response:

     {
       "invoice": "lni1qqg0qe01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
       "changes": {}
     }

     Example 2:

     Request:

     $ lightning-cli fetchinvoice -k "offer"="lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000" "amount_msat"=2000000 "quantity"=2

     {
       "id": "example:fetchinvoice#2",
       "method": "fetchinvoice",
       "params": {
	 "offer": "lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000",
	 "amount_msat": 2000000,
	 "quantity": 2
       }
     }

     Response:

     {
       "invoice": "lni1qqg0qe02020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
       "changes": {}
     }

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