Glossary / Lightning & layer 2
Invoice expiry
- What is Invoice expiry?
- Invoice expiry is the x field of a BOLT11 payment request, a number of seconds counted from the invoice's own timestamp, after which payer and payee should both refuse it.
Every Lightning invoice carries a deadline, and the countdown begins at the moment the invoice was signed rather than the moment it reached you. With no x field present, the default is 3600 seconds, one hour. So an invoice that sat in a chat thread for most of that hour can fail minutes after it reaches you, for no visible reason.
How it works
Invoice expiry travels as tagged field type 6, written as the letter x, carrying a big-endian count of seconds.
A BOLT11 string opens with a 35 bit timestamp counting seconds since 1 January 1970 UTC, then the tagged fields, then a signature. Expiry is one of those fields and it is relative: the deadline is that timestamp plus the expiry, so nothing in the invoice states a readable clock time. BOLT11 tells a payer not to attempt a payment once the sum has passed, and tells the payee not to accept one either.
Both instructions are a SHOULD rather than a MUST, so an expired invoice is not cryptographically dead. The payment hash still works; what stops the payment is policy on both ends rather than a lock. Your wallet declines to try, and a node that has discarded the preimage could not settle anyway.
The value is packed into groups of five bits and must use the shortest length that fits, with no leading zero groups. The spec's own examples show the range: 60 seconds occupies two groups, written pu, and 604800 seconds occupies four, written jw5q. An encoder that pads the field is not merely untidy: readers are told to treat an invoice with a non-minimal x, c or 9 field as invalid.
Nobody can extend an invoice once it is issued. The signature covers the human readable prefix and the whole data part, so editing one character of the expiry breaks it. A merchant who wants to give you longer must issue a new request and sign it again.
The one hour default was not picked at random: the spec's rationale says it leaves time to pay on-chain instead, through the fallback address the f field can carry.
Where you see it
Invoice expiry surfaces as the countdown ring around a QR code, as a line labelled expiry in any decoder, and as the refusal a wallet gives when you paste something stale.
The spec's test vectors show both ends of the range. An invoice for 2500 micro-bitcoin described as 1 cup coffee sets the expiry to 60 seconds, because it pins a three dollar price at the counter. An invoice from the Blockstream Store, for 88.85 USD of merchandise including a Ledger Nano S, sets it to 604800 seconds, seven days, because an order confirmation is a bill rather than a countertop.
Where the invoice is minted decides who chose the number. Phoenix, which we review, runs a real Lightning node on the handset rather than an account on a server, so the expiry in a receive request is its own node's setting. With a custodial app the figure comes from the operator, and decoding one of its invoices is usually the only way to learn it.
Invoice expiry vs CLTV expiry delta
Invoice expiry and CLTV expiry delta are both clocks on a Lightning payment, and they run in different units over different halves of the problem.
Invoice expiry is wall clock seconds counted from the invoice timestamp, and it decides whether the payment may be attempted at all. A CLTV expiry delta is measured in blocks, and the c field of the same invoice carries the recipient's minimum for the final hop, which a payer must treat as at least 18 blocks when the field is absent. One tells you whether to start; the other tells you how long your money can sit locked in an HTLC after you have.