LIGHTNING-DELINVOICE(7)

💖 NAME 💖

Okay so bestie, welcome to lightning-delinvoice(7) — the manual page for delinvoice, the command for removing an invoice (or just its description) 💅. It's giving cleanup era, no cap.

✨ SYNOPSIS ✨

delinvoice label status [desconly]

🌸 DESCRIPTION 🌸

The delinvoice RPC command removes an invoice with status as given in listinvoices, or — with desconly set — removes its description. Iconic behavior, honestly ✨.

• label — one of these, bestie; it's the label of the invoice to be deleted:
  • (string)
  • (u64)
• status — (string) (one of "paid", "expired", "unpaid"): the label of the invoice to be deleted. The caller should be particularly aware of the error case caused by the status changing just before this command is invoked! 😭 This is the “it was fine a second ago” of RPCs.
• desconly — (boolean, optional): if set to True, the invoice is not deleted, but has its description removed. This can save space with very large descriptions, as would be used with lightning-invoice(7) deschashonly. It's giving minimalist era 💅.

👑 RETURN VALUE 👑

Note: the return is the same as an object from lightning-listinvoices(7). On success, an object is returned, containing:

• label — (string): unique label given at creation time.
• payment_hash — (hash): the hash of the payment_preimage which will prove payment.
• created_index — (u64): 1-based index indicating order this invoice was created in. (added v23.08)
• status — (string) (one of "paid", "expired", "unpaid"): state of invoice.
• expires_at — (u64): UNIX timestamp when invoice expires (or expired).
• bolt11 — (string, optional): BOLT11 string.
• bolt12 — (string, optional): BOLT12 string.
• amount_msat — (msat, optional): the amount required to pay this invoice.
• description — (string, optional): description used in the 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 bolt12 is present:

• local_offer_id — (hex, optional): offer for which this invoice was created.
• invreq_payer_note — (string, optional): the optional invreq_payer_note from invoice_request which created this invoice.

If status is "paid":

• pay_index — (u64): unique index for this invoice payment.
• amount_received_msat — (msat): how much was actually received.
• paid_at — (u64): UNIX timestamp of when payment was received.
• payment_preimage — (secret): SHA256 of this is the payment_hash offered in the invoice.

💀 ERRORS 💀

The following errors may be reported:

• -1 — database error.
• 905 — an invoice with that label does not exist.
• 906 — the invoice status does not match the parameter. An error object will be returned as error data, containing current_status and expected_status fields. This is most likely due to the status of the invoice changing just before this command is invoked. The “not me refreshing at the exact wrong moment” energy 😭.
• 908 — the invoice already has no description, and desconly was set.

🫶 AUTHOR 🫶

Rusty Russell rusty@rustcorp.com.au is mainly responsible. Main character energy, honestly 👑.

🔥 SEE ALSO 🔥

• lightning-listinvoices(7)
• lightning-waitinvoice(7)
• lightning-invoice(7)
• lightning-autoclean-status(7)

🌈 RESOURCES 🌈

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

🧚 EXAMPLES 🧚

✨ Example 1 ✨

Request:

$ lightning-cli delinvoice -k "label"="lbl_l36" "status"="unpaid"

{
  "id": "example:delinvoice#1",
  "method": "delinvoice",
  "params": {
    "label": "lbl_l36",
    "status": "unpaid"
  }
}

Response:

{
  "label": "lbl_l36",
  "bolt11": "lnbcrt222n1pnt3005720bolt113000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "payment_hash": "paymenthashdelinv10101010101010101010101010101010101010101010101",
  "amount_msat": 50000000,
  "status": "unpaid",
  "description": "l36 description",
  "expires_at": 1739000000,
  "created_index": 9
}

✨ Example 2 ✨

Request:

$ lightning-cli delinvoice -k "label"="lbl_l37" "status"="paid" "desconly"=True

{
  "id": "example:delinvoice#2",
  "method": "delinvoice",
  "params": {
    "label": "lbl_l37",
    "status": "paid",
    "desconly": true
  }
}

Response:

{
  "label": "lbl_l37",
  "bolt11": "lnbcrt222n1pnt3005720bolt113000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "payment_hash": "paymenthashdelinv20202020202020202020202020202020202020202020202",
  "amount_msat": 50000000,
  "status": "paid",
  "pay_index": 9,
  "amount_received_msat": 50000000,
  "paid_at": 1738500000,
  "payment_preimage": "paymentpreimagedelinv01010101010101010101010101010101010101010101",
  "expires_at": 1739000000,
  "created_index": 10,
  "updated_index": 9
}

---

Okay that's the whole page, bestie — source/version is Core Lightning v26.06.9, and the footer didn't print a date, so no fake date energy from me. Catch you later for more lightning-delinvoice(7) adventures 🫶💖