# Invoices ## Create an invoice Scope needed: `invoices:create` Creates a new invoice to receive lightning payments. `POST` `https://api.getalby.com/invoices` Creates a new invoice #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | description\_hash | String | Pass a hash of the description instead of the description (for private or long descriptions) | | amount\* | int64 | amount, must be a whole number in sats (millisats are not supported). | | description | String | Arbitrary text (included in the BOLT11 invoice) | | currency | String | currency of the invoice. Default is "btc" | | memo | String | same as "description" field. | | comment | String | Arbitrary text to save alongside the invoice (not included in the BOLT11 invoice) | | metadata | Object | Arbitrary data to save alongside the invoice (not included in the BOLT11 invoice) | | payer\_name | String | Name of payer (not included in the BOLT11 invoice) | | payer\_email | String | Email of payer (not included in the BOLT11 invoice) | | payer\_pubkey | String | Nostr or node pubkey of payer to store with the invoice (not included in the BOLT11 invoice) | {% tabs %} {% tab title="200: OK " %} ```javascript { "expires_at": "2022-06-02T08:31:15Z", "payment_hash": "01ac4cfb2565d1221897a3bf7304c71fb47b1104fd591c8b91b903c878d16b84", "payment_request": "lnbcrt10u1p3fsa2jpp5qxkye7e9vhgjyxyh5wlhxpx8r768kygyl4v3ezu3hypus7x3dwzqhp5s6dz9ye889e8uyaxjzjlkh3vtwes50mhyvfraf3y6l3yk8t2mlgscqzpgxqyz5vqsp5zt95vajqwya7haely3p0ev2jg4v6lr84up4ujm5auk8u74xggtas9qyyssq7lmukwlctr2y4gcuw9324gfxefug45zrrywrp5l3fmn85zulk6z44pqx7vywp7zsks2r5rclang06akp6054tlgfad80ktzg9vwyatcqz6ssya"," } ``` {% endtab %} {% tab title="400: Bad Request Invalid request body or Invoice could not be created" %} ```javascript { "code": 0, "error": true, "message": "string" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Invoice could not be created" %} **NOTE: this error code is currently unused, but is planned to be used in the near future.** {% endtab %} {% endtabs %} {% hint style="info" %} Looking to create invoices for a lightning address without requiring scope? Try our [Lightning Address details API](/developer-guide/developer-guide/alby-wallet-api/lightning-address-details-proxy.md) which uses the LNURL protocol. {% endhint %} ## Get incoming invoice history Scope needed: `invoices:read` Lists all settled incoming invoices, including boostagram and LNURL metadata. `GET` `https://api.getalby.com/invoices/incoming` Lists all incoming invoices #### Query Parameters | Name | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------------- | | q\[created\_at\_gt] | Int | Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321) | | q\[created\_at\_lt] | Int | Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321) | | q\[since] | String | Filter invoices created after the given invoice identifier | | page | Int | Page number (1 is the first page) | | items | Int | Items per page (Default 25) | | q\[before] | String | Filter invoices created before the given invoice identifier | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "amount": 3, "boostagram": { "action": "stream", "app_name": "Fountain", "boost_link": "https://fountain.fm/episode/xxx", "episode": "Your episode", "feedID": 123456789, "itemID": 123456789, "message": null, "name": "Podcaster", "podcast": "Your podcast", "sender_id": "jack", "sender_name": "@jack", "time": "00:02:07", "ts": 127, "url": "https://media.rss.com/yourpodcast/feed.xml", "value_msat_total": 3000 }, "comment": null, "created_at": "2022-07-05T17:02:20.343Z", "creation_date": 1657040540, "currency": "btc", "custom_records": { "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=", "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=", "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9" }, "description_hash": null, "expires_at": "2022-07-05T17:17:20.000Z", "expiry": 900, "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA", "keysend_message": null, "memo": "", "payer_name": "@aduin18", "payer_pubkey": null, "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd", "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "payment_request": "", "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "settled": true, "settled_at": "2022-07-05T17:02:20.000Z", "state": "SETTLED", "type": "incoming", "value": 3 } ] ``` {% endtab %} {% endtabs %} ## Get outgoing invoice history Scope needed: `transactions:read` Lists all settled outgoing invoices, including boostagrams information. `GET` `https://api.getalby.com/invoices/outgoing` Lists all outgoing invoices #### Query Parameters | Name | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------------- | | q\[since] | String | Filter invoices created after the given invoice identifier | | q\[created\_at\_lt] | Int | Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321) | | q\[created\_at\_gt] | Int | Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321) | | page | Int | Page number (1 is the first page) | | items | Int | Items per page (Default 25) | | q\[before] | String | Filter invoices created before the given invoice identifier | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "amount": 300, "boostagram": null, "comment": null, "created_at": "2022-06-21T11:04:07.237Z", "creation_date": 1655809370, "currency": "btc", "custom_records": null, "description_hash": null, "expires_at": "2022-06-21T11:17:50.000Z", "expiry": 900, "identifier": "cdyv5AUpMZeEgEAfsJrbTSMc", "keysend_message": null, "memo": "Feed Chickens @ pollofeed.com", "payer_name": null, "payer_pubkey": null, "payment_hash": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678", "payment_request": "lnbc3u1p3trf2ksp54a202vea0n3cr9u6evh7rqt858e4jzlwzqvjc4q2la0df2n6qntspp5nplcl8ah2zrnrqargutrt8y30ktpkzc6s9hyk9m2vd3y4zvfweuqdp0gejk2epqgd5xjcmtv4h8xgzqypcx7mrvdanx2ety9e3k7mgxqz95cqpjrzjq2j39c6dx9ea09gkx000aumgv4m4ghu444x7pztl8gnpfka5amkazz60ysqq4dcqqvqqqqqqqqqqqvsq9q9qyysgq4me57k6m7xxsf3fhdq86jk6e29hdsl9h4vjqm5y47vp8cgcfwcfsd7f27t6t73sw87g8l09j4kjxz77dl0kht86qwmxqf9l0nrqwkuqp9yex3z", "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd", "r_hash_str": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678", "settled": true, "settled_at": "2022-06-21T11:04:05.000Z", "state": "SETTLED", "type": "outgoing", "value": 300 }, ] ``` {% endtab %} {% endtabs %} ## Get all invoice history Scope needed: `invoices:read` Combination of incoming and outgoing invoice histories. Possible query parameters are the same as above. `GET` `https://api.getalby.com/invoices` #### Query Parameters | Name | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------------- | | q\[since] | String | Filter invoices created after the given invoice identifier | | q\[created\_at\_lt] | Int | Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321) | | q\[created\_at\_gt] | Int | Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321) | | page | Int | Page number (1 is the first page) | | items | Int | Items per page (Default 25) | | q\[before] | String | Filter invoices created before the given invoice identifier | {% tabs %} {% tab title="200: OK " %} ``` [ { "amount": 300, "boostagram": null, "comment": null, "created_at": "2022-06-21T11:04:07.237Z", "creation_date": 1655809370, "currency": "btc", "custom_records": null, "description_hash": null, "expires_at": "2022-06-21T11:17:50.000Z", "expiry": 900, "identifier": "cdyv5AUpMZeEgEAfsJrbTSMc", "keysend_message": null, "memo": "Feed Chickens @ pollofeed.com", "payer_name": null, "payer_pubkey": null, "payment_hash": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678", "payment_request": "lnbc3u1p3trf2ksp54a202vea0n3cr9u6evh7rqt858e4jzlwzqvjc4q2la0df2n6qntspp5nplcl8ah2zrnrqargutrt8y30ktpkzc6s9hyk9m2vd3y4zvfweuqdp0gejk2epqgd5xjcmtv4h8xgzqypcx7mrvdanx2ety9e3k7mgxqz95cqpjrzjq2j39c6dx9ea09gkx000aumgv4m4ghu444x7pztl8gnpfka5amkazz60ysqq4dcqqvqqqqqqqqqqqvsq9q9qyysgq4me57k6m7xxsf3fhdq86jk6e29hdsl9h4vjqm5y47vp8cgcfwcfsd7f27t6t73sw87g8l09j4kjxz77dl0kht86qwmxqf9l0nrqwkuqp9yex3z", "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd", "r_hash_str": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678", "settled": true, "settled_at": "2022-06-21T11:04:05.000Z", "state": "SETTLED", "type": "outgoing", "value": 300 }, { "amount": 3, "boostagram": { "action": "stream", "app_name": "Fountain", "boost_link": "https://fountain.fm/episode/xxx", "episode": "Your episode", "feedID": 123456789, "itemID": 123456789, "message": null, "name": "Podcaster", "podcast": "Your podcast", "sender_id": "jack", "sender_name": "@jack", "time": "00:02:07", "ts": 127, "url": "https://media.rss.com/yourpodcast/feed.xml", "value_msat_total": 3000 }, "comment": null, "created_at": "2022-07-05T17:02:20.343Z", "creation_date": 1657040540, "currency": "btc", "custom_records": { "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=", "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=", "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9" }, "description_hash": null, "expires_at": "2022-07-05T17:17:20.000Z", "expiry": 900, "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA", "keysend_message": null, "memo": "", "payer_name": "@aduin18", "payer_pubkey": null, "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "payment_request": "", "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd", "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "settled": true, "settled_at": "2022-07-05T17:02:20.000Z", "state": "SETTLED", "type": "incoming", "value": 3 } ] ``` {% endtab %} {% endtabs %} ## Get a specific invoice Scope needed: `invoices:read` Get details about specific invoice. Can be both incoming or outgoing. {% hint style="warning" %} Unsettled invoices can only be retrieved if they were created through the Alby API or Nostr Wallet Connect (using ). Unsettled Invoices created directly using the Lndhub API will return a 404. {% endhint %} `GET` `https://api.getalby.com/invoices/{payment_hash}` Get details about specific invoice. Can be both incoming or outgoing #### Path Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | payment\_hash\* | String | The payment hash of the payment | {% tabs %} {% tab title="200: OK Settled invoice" %} ```javascript { "amount": 3, "boostagram": { "action": "stream", "app_name": "Fountain", "boost_link": "https://fountain.fm/episode/xxx", "episode": "Your episode", "feedID": 123456789, "itemID": 123456789, "message": null, "name": "Podcaster", "podcast": "Your podcast", "sender_id": "jack", "sender_name": "@jack", "time": "00:02:07", "ts": 127, "url": "https://media.rss.com/yourpodcast/feed.xml", "value_msat_total": 3000 }, "comment": null, "created_at": "2022-07-05T17:02:20.343Z", "creation_date": 1657040540, "currency": "btc", "custom_records": { "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=", "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=", "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9" }, "description_hash": null, "expires_at": "2022-07-05T17:17:20.000Z", "expiry": 900, "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA", "keysend_message": null, "memo": "", "payer_name": "@aduin18", "payer_pubkey": null, "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "payment_request": "", "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b", "settled": true, "settled_at": "2022-07-05T17:02:20.000Z", "state": "SETTLED", "type": "incoming", "value": 3 } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { "code": 0, "error": true, "message": "string" } ``` {% endtab %} {% tab title="200: OK Unsettled invoice" %} ```json { "amount": 1000, "boostagram": null, "comment": null, "created_at": "2023-11-08T04:58:11.205Z", "creation_date": 1699419491, "currency": "btc", "custom_records": null, "description_hash": null, "expires_at": "2023-11-09T04:58:11.000Z", "expiry": 86400, "fiat_currency": "USD", "fiat_in_cents": 36, "identifier": "6vaChhm17PqoJ5LJQi1THpUC", "keysend_message": null, "memo": null, "payer_name": null, "payer_email": null, "payer_pubkey": null, "payment_hash": "c169e73f4eb85de8bfa345d0b650b6ffb64054ebb57571e3d3a235b6ba616fe0", "payment_request": "lnbc10u1pj5k9trpp5c957w06whpw730arghgtv59kl7myq48tk46hrc7n5g6mdwnpdlsqdp8xemxzsmgdpknzd6sw9h55d2vffgkjv25fpc92sccqzzsxqyz5vqsp52aauy758lcg0hkda65kcrffrlsgum97gt6ywu8r0fz6cacwy0x7q9qyyssqyafv2eamugl5e79wrcu7pzllwyq8kcn5fw8l6njjqtzsfthsd6452nwyjxmpmpek8jrt4j6vtm4wq8dkj34wewz0707yvdgqxqsuhyspxmsmld", "r_hash_str": "c169e73f4eb85de8bfa345d0b650b6ffb64054ebb57571e3d3a235b6ba616fe0", "settled": null, "settled_at": null, "state": "CREATED", "type": "incoming", "value": 1000, "metadata": null, "destination_alias": null, "destination_pubkey": null, "first_route_hint_pubkey": null, "first_route_hint_alias": null, "qr_code_png": "https://getalby.com/api/invoices/6vaChhm17PqoJ5LJQi1THpUC.png", "qr_code_svg": "https://getalby.com/api/invoices/6vaChhm17PqoJ5LJQi1THpUC.svg" } ``` {% endtab %} {% endtabs %} ## Decode an invoice Decode an invoice. Will also add the alias of the receiving node & route hints (LSP's). ## Decode an invoice `GET` `https://api.getalby.com/decode/bolt11/{bolt11_invoice}` Will also add the alias of the receiving node & route hints (LSP's). #### Path Parameters | Name | Type | Description | | ------------------------------------------------- | ------ | -------------------------- | | bolt11\_invoice\* | String | Needs to be a valid bolt11 | {% tabs %} {% tab title="200: OK " %} ```json { "currency": "bc", "created_at": 1693210330, "expiry": 86400, "payee": "030a58b8653d32b99200a2334cfe913e51dc7d155aa0116c176657a4f1722677a3", "msatoshi": 23000, "description": "Alby invoice", "payment_hash": "184d3946b916dfba520b242b30254c53dd9c538158cac37df2a54fad7ed99b16", "min_final_cltv_expiry": 80, "amount": 23, "payee_alias": "getalby.com", "route_hint_aliases": [] } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://guides.getalby.com/developer-guide/developer-guide/alby-wallet-api/reference/api-reference/invoices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.