# Invoices

## Create an invoice

Scope needed: `invoices:create`

Creates a new invoice to receive lightning payments.

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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](https://guides.getalby.com/developer-guide/developer-guide/alby-wallet-api/lightning-address-details-proxy) which uses the LNURL protocol.
{% endhint %}

## Get incoming invoice history

Scope needed: `invoices:read`

Lists all settled incoming invoices, including boostagram and LNURL metadata.

<mark style="color:blue;">`GET`</mark> `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.

<mark style="color:blue;">`GET`</mark> `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.

<mark style="color:blue;">`GET`</mark> `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 <https://nwc.getalby.com/>). Unsettled Invoices created directly using the Lndhub API will return a 404.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | 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

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | 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 %}