core-lightning/doc/schemas/lightning-delinvoice.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "rpc": "delinvoice",
  "title": "Command for removing an invoice (or just its description)",
  "description": [
    "The **delinvoice** RPC command removes an invoice with *status* as given in **listinvoices**, or with *desconly* set, removes its description."
  ],
  "request": {
    "required": [
      "label",
      "status"
    ],
    "properties": {
      "label": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "u64"
          }
        ],
        "description": [
          "Label of the invoice to be deleted."
        ]
      },
      "status": {
        "type": "string",
        "description": [
          "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!"
        ],
        "enum": [
          "paid",
          "expired",
          "unpaid"
        ]
      },
      "desconly": {
        "type": "boolean",
        "description": [
          "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*."
        ]
      }
    }
  },
  "response": {
    "required": [
      "label",
      "payment_hash",
      "status",
      "created_index",
      "expires_at"
    ],
    "properties": {
      "label": {
        "type": "string",
        "description": [
          "Unique label given at creation time."
        ]
      },
      "bolt11": {
        "type": "string",
        "description": [
          "BOLT11 string."
        ]
      },
      "bolt12": {
        "type": "string",
        "description": [
          "BOLT12 string."
        ]
      },
      "amount_msat": {
        "type": "msat",
        "description": [
          "The amount required to pay this invoice."
        ]
      },
      "description": {
        "type": "string",
        "description": [
          "Description used in the invoice."
        ]
      },
      "payment_hash": {
        "type": "hash",
        "description": [
          "The hash of the *payment_preimage* which will prove payment."
        ]
      },
      "created_index": {
        "type": "u64",
        "added": "v23.08",
        "description": [
          "1-based index indicating order this invoice was created in."
        ]
      },
      "updated_index": {
        "type": "u64",
        "added": "v23.08",
        "description": [
          "1-based index indicating order this invoice was changed (only present if it has changed since creation)."
        ]
      },
      "status": {
        "type": "string",
        "description": [
          "State of invoice."
        ],
        "enum": [
          "paid",
          "expired",
          "unpaid"
        ]
      },
      "expires_at": {
        "type": "u64",
        "description": [
          "UNIX timestamp when invoice expires (or expired)."
        ]
      }
    },
    "allOf": [
      {
        "if": {
          "required": [
            "bolt12"
          ]
        },
        "then": {
          "required": [],
          "additionalProperties": false,
          "properties": {
            "label": {},
            "bolt12": {},
            "status": {},
            "expires_at": {},
            "msatoshi": {},
            "amount_msat": {},
            "description": {},
            "payment_hash": {},
            "pay_index": {},
            "created_index": {},
            "updated_index": {},
            "amount_received_msat": {},
            "paid_at": {},
            "payment_preimage": {},
            "local_offer_id": {
              "type": "hex",
              "description": [
                "Offer for which this invoice was created."
              ]
            },
            "invreq_payer_note": {
              "type": "string",
              "description": [
                "The optional *invreq_payer_note* from invoice_request which created this invoice."
              ]
            }
          }
        },
        "else": {
          "required": [
            "bolt11"
          ],
          "additionalProperties": false,
          "properties": {
            "label": {},
            "bolt11": {},
            "status": {},
            "expires_at": {},
            "msatoshi": {},
            "amount_msat": {},
            "description": {},
            "payment_hash": {},
            "pay_index": {},
            "created_index": {},
            "updated_index": {},
            "amount_received_msat": {},
            "msatoshi_received": {},
            "paid_at": {},
            "payment_preimage": {}
          }
        }
      },
      {
        "if": {
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "paid"
              ]
            }
          }
        },
        "then": {
          "additionalProperties": false,
          "required": [
            "pay_index",
            "amount_received_msat",
            "paid_at",
            "payment_preimage"
          ],
          "properties": {
            "label": {},
            "bolt11": {},
            "bolt12": {},
            "status": {},
            "expires_at": {},
            "msatoshi": {},
            "amount_msat": {},
            "description": {},
            "payment_hash": {},
            "invreq_payer_note": {},
            "local_offer_id": {},
            "created_index": {},
            "updated_index": {},
            "pay_index": {
              "type": "u64",
              "description": [
                "Unique index for this invoice payment."
              ]
            },
            "amount_received_msat": {
              "type": "msat",
              "description": [
                "How much was actually received."
              ]
            },
            "paid_at": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when payment was received."
              ]
            },
            "payment_preimage": {
              "type": "secret",
              "description": [
                "SHA256 of this is the *payment_hash* offered in the invoice."
              ]
            }
          }
        },
        "else": {
          "additionalProperties": false,
          "properties": {
            "label": {},
            "bolt11": {},
            "bolt12": {},
            "status": {},
            "msatoshi": {},
            "amount_msat": {},
            "description": {},
            "payment_hash": {},
            "expires_at": {},
            "created_index": {},
            "updated_index": {},
            "pay_index": {},
            "invreq_payer_note": {},
            "local_offer_id": {}
          }
        }
      }
    ],
    "pre_return_value_notes": [
      "Note: The return is the same as an object from lightning-listinvoices(7)."
    ]
  },
  "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.",
    "- 908: The invoice already has no description, and *desconly* was set."
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
  ],
  "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": [
    {
      "request": {
        "id": "example:delinvoice#1",
        "method": "delinvoice",
        "params": {
          "label": "invlabel2",
          "status": "unpaid",
          "desconly": true
        }
      },
      "response": {
        "label": "invlabel2",
        "bolt11": "lnbcrt420p1pja0tefsp5vvzg40t4g24l0eqk0jch7mc6jm3ec52ts8w8gwzpwtx9c8nv05rspp533e9csxurt7j9sn2cx7hsn6m00475qgrau8sux5r7djpdedwy2fshp5xqsmrtgfcwsnhxcxmf3tuc65kl6fxvqhvujfmxw2kpeh95yy2x8sxqyjw5qcqp99qxpqysgqgfjrz4q5zcq2lluxxg9h475mq2d3w0tpdstm5274zmhadjl8cqapylfskzk96apka5599a2flm90rmavsk7q8mhh87yle3sgh5vrlycq72fern",
        "payment_hash": "8c725c40dc1afd22c26ac1bd784f5b7bebea0103ef0f0e1a83f36416e5ae2293",
        "amount_msat": 42,
        "status": "unpaid",
        "expires_at": 1709238697,
        "created_index": 3
      }
    },
    {
      "request": {
        "id": "example:delinvoice#2",
        "method": "delinvoice",
        "params": {
          "label": "keysend-1708640419.666098582",
          "status": "paid"
        }
      },
      "response": {
        "label": "keysend-1708640419.666098582",
        "bolt11": "lnbcrt1pja0j9rsp5tg3zvj846gcdzw394njazq40s946sq2ur3hkl4xu4xudtjdtckxspp5fuunrfzsnyz2uxjmg2n95mqhghv4fpvv2kud3kvq4fkys3vmzu5sdqvddjhjum9dejqxqyjw5qcqp99qxpqysgqwt7r0gjlgt7zrfldc3um9myfc36acpqnsdn77c2m42facjtps30yufc5nsmwzhgexlj59f6xa5hess6e3tqrxynt9fejzj3rrshddtcqnappmj",
        "payment_hash": "4f3931a4509904ae1a5b42a65a6c1745d954858c55b8d8d980aa6c48459b1729",
        "status": "paid",
        "pay_index": 1,
        "amount_received_msat": 10000000,
        "paid_at": 1708640419,
        "payment_preimage": "b760af47f456a217e8dfda21a282f1f78c903487c1b21b3b318135f75aa3bf11",
        "description": "keysend",
        "expires_at": 1709245219,
        "created_index": 1,
        "updated_index": 1
      }
    }
  ]
}