> ## Documentation Index > Fetch the complete documentation index at: https://docs.payra.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoices > Read your invoices and each one's payment link, to show a Pay button in your own portal or print the link on your own documents. An **invoice** is one of your workspace's invoices: the same record your team sees under **Invoices** in the Payra dashboard, whether it came from your ERP through Payra Connect or was created in the dashboard. The API reads them; it does not create or change them. Each open invoice carries its **payment link**, the hosted page where the customer pays it by card or bank account. Put that link behind a **Pay** button in your own customer portal, or on the invoice document you send, and Payra collects the payment, records it on the invoice and, for ERP-synced invoices, posts it back to the ERP as it does for every other payment. By the number your customer sees, or by your ERP's id for it: ```bash theme={null} curl "https://api-dashboard.payra.com/v1/invoices?number=INV-1042" \ -H "Authorization: Bearer sk_test_..." ``` ```json Response theme={null} { "object": "list", "data": [ { "object": "invoice", "id": "019e2b4c-7a1d-7c3e-9f20-5b8d4e6a1c31", "number": "INV-1042", "external_id": "SO-55512", "customer": "019e2b4c-7a1d-7c3e-9f20-5b8d4e6a1c30", "status": "open", "past_due": false, "currency": "USD", "total": 125000, "amount_paid": 25000, "amount_pending": 0, "amount_due": 100000, "invoice_date": "2026-09-30", "due_date": "2026-10-30", "payment_url": "https://dashboard.payra.com/pay/4f8c1d2e3b5a6c7d8e9f0a1b2c3d4e5f", "livemode": true, "created_at": "2026-09-30T23:00:40.670Z" } ], "has_more": false } ``` `external_id` finds at most one invoice. `number` usually does too, but a number can repeat across customers, so read the list. With Payra's `id`, `GET /invoices/{id}` reads the invoice directly. ```bash theme={null} curl "https://api-dashboard.payra.com/v1/invoices?customer=019e2b4c-7a1d-7c3e-9f20-5b8d4e6a1c30&status=open" \ -H "Authorization: Bearer sk_test_..." ``` `customer` is the id from [Customers](/customers), the same one a payment carries. The list runs newest first and [pages](/pagination) with `limit` and `starting_after`. Send the customer to `payment_url`. The page shows the invoice and takes the payment; when it succeeds, the invoice's `amount_paid` and `status` change on your next read. ## Amounts and status Amounts are integers in the currency's smallest unit (cents), as everywhere in the API. * `total` is the invoice total. * `amount_paid` is what was collected, refunds netted out. * `amount_pending` is what charges still processing will collect, such as a bank debit that has not settled. It is owed until a charge fails, and cannot be paid a second time meanwhile. * `amount_due` is what a payer can still pay today: the total less what was paid, pending or written off in the dashboard, and `0` once the invoice is `paid` or `canceled` (even when your ERP marked it paid without a payment through Payra). An early-payment discount the invoice offers is applied on the payment page, not here. `status` is `open` while the invoice owes money, whether it has been sent or is still scheduled to be sent, and `paid` or `canceled` once settled. `past_due` is true from the day after `due_date` while an open invoice is unpaid; an invoice still scheduled to be sent is never past due. Drafts, and ERP invoices still awaiting approval in the dashboard, are not listed. ## The payment link `payment_url` is the link Payra prints on its own invoice emails and reminders: the same URL every time you read the invoice while it works, so you can store it or print it. It is `null` when there is nothing a payer could use: the invoice is settled, nothing is left to pay while a charge is pending, the invoice or its link expired, the link was revoked, or no link was ever made (an invoice created in the dashboard and never sent). Invoices that arrive from an ERP get their link as they arrive. Sending the invoice again from the dashboard makes a new link; the earlier one keeps working. A payment made through the link is recorded on the invoice and shown in the dashboard like any other. It is not a payment you created through the API, so it does not appear under [Payments](/payments) or in [webhook](/webhooks) events: read the invoice to learn that it was paid, or let your ERP learn it through Payra Connect. ## Scopes and errors Reading and listing need `invoices:read`. Keys created before this scope existed with every scope were given it; a key you narrowed on purpose was not, and a new key gets it from the **Invoices** group. | Code | Why | | - | - | | `parameter_invalid` (400) | A `limit` out of range, a `status` other than `open`, `paid` or `canceled`, a filter longer than 100 characters, an `id` longer than 64 characters, or a `starting_after` that is not an invoice of your workspace; `param` names the field | | `resource_missing` (404) | No invoice with that id in your workspace, or it is a draft or still awaiting approval | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.