--- title: invoices.get | Doing Work API description: One invoice with doc_no and doc_label (I-12), its lines, what has been paid, the balance, the due date, and whether a bank payment is still clearing. url: https://doingwork.work/docs/reference/invoices-get/ --- # invoices.get One invoice with doc_no and doc_label (I-12), its lines, what has been paid, the balance, the due date, and whether a bank payment is still clearing. payments lists each card or bank payment: id is the charge_id invoices.refund takes, plus amount, method, status, paid_at, refunded amount and refunds. refunded_minor is money sent back. net_collected_minor is what remains of the payment after that. A payment status is refunded or partially_refunded once the processor confirms. collected_minor stays the amount that was paid, and balance_minor stays what is still owed, which is 0 after a refund. display_status is payment_pending while a bank payment clears (3 to 5 business days), otherwise the invoice status. last_bank_payment_failed_at is set when the latest bank payment failed and the customer can pay again. | | | |---|---| | Who | Agents can call this | | REST | `GET /v1/invoices/get` | | MCP tool | `invoices_get` | | Writes | no | | Area | [Shop](https://doingwork.work/docs/reference/#shop) | ## When to use it One invoice with doc_no and doc_label (I-12), its lines, what has been paid, the balance, the due date, and whether a bank payment is still clearing. payments lists each card or bank payment: id is the charge_id invoices.refund takes, plus amount, method, status, paid_at, refunded amount and refunds. ## What to tell the owner Tell them what you found in plain words. Don't read back raw fields. ## Input | Field | Type | Required | |---|---|---| | `invoice_id` | string (uuid) | yes | ## Example ```http GET https://doingwork.work/v1/invoices/get?invoice_id=00000000-0000-4000-8000-000000000000 ``` ## Output | Field | Type | Always there | |---|---|---| | `invoice_id` | string (uuid) | yes | | `job_id` | string (uuid) | yes | | `status` | string | yes | | `currency` | string | yes | | `doc_no` | integer | yes | | `doc_label` | string | yes | | `total_minor` | integer | yes | | `collected_minor` | integer | yes | | `refunded_minor` | integer | yes | | `net_collected_minor` | integer | yes | | `balance_minor` | integer | yes | | `written_off_minor` | integer | yes | | `deposit_minor` | ['integer', 'null'] | yes | | `issued_at` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | yes | | `due_on` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', ')'] | yes | | `memo` | ['string', 'null'] | yes | | `bank_payment_clearing` | boolean | yes | | `display_status` | string | yes | | `last_bank_payment_failed_at` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | yes | | `payments` | array | yes | | `payments[].id` | string (uuid) | yes | | `payments[].invoice_id` | string (uuid) | yes | | `payments[].amount_minor` | integer | yes | | `payments[].method` | string | yes | | `payments[].status` | string | yes | | `payments[].paid_at` | string (date-time) | yes | | `payments[].refunded_minor` | integer | yes | | `payments[].refunds` | array | yes | | `payments[].refunds[].id` | string (uuid) | yes | | `payments[].refunds[].amount_minor` | integer | yes | | `payments[].refunds[].created_at` | string (date-time) | yes | | `lines` | array | yes | | `lines[].position` | integer | yes | | `lines[].description` | string | yes | | `lines[].quantity` | number | yes | | `lines[].unit_price_minor` | integer | yes | | `lines[].kind` | string | yes | | `lines[].taxable` | boolean | yes | | `lines[].amount_minor` | integer | yes | | `tax` | object | no | | `tax.name` | ['string', 'null'] | yes | | `tax.jurisdiction` | ['string', 'null'] | yes | | `tax.rate_bps` | integer | yes | | `tax.taxable_minor` | integer | yes | | `tax.tax_minor` | integer | yes | | `next_actions` | array | yes | | `next_actions[].say` | string | yes | | `next_actions[].op` | ['string', 'null'] | yes | | `next_actions[].when` | string (one of now, later, check, tell_human) | yes | | `next_actions[].due_at` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | no | | `next_actions[].args_hint` | string | no | ```json { "invoice_id": "00000000-0000-4000-8000-000000000000", "job_id": "00000000-0000-4000-8000-000000000000", "status": "...", "currency": "...", "doc_no": 1, "doc_label": "...", "total_minor": 50000, "collected_minor": 50000, "refunded_minor": 50000, "net_collected_minor": 50000, "balance_minor": 50000, "written_off_minor": 50000, "deposit_minor": "...", "issued_at": "...", "due_on": "...", "memo": "...", "bank_payment_clearing": true, "display_status": "...", "last_bank_payment_failed_at": "...", "payments": [ { "id": "00000000-0000-4000-8000-000000000000", "invoice_id": "00000000-0000-4000-8000-000000000000", "amount_minor": 50000, "method": "...", "status": "...", "paid_at": "...", "refunded_minor": 50000, "refunds": [ { "id": "00000000-0000-4000-8000-000000000000", "amount_minor": 50000, "created_at": "..." } ] } ], "lines": [ { "position": 1, "description": "40 gallon gas heater, installed", "quantity": "...", "unit_price_minor": 50000, "kind": "...", "taxable": true, "amount_minor": 50000 } ], "next_actions": [ { "say": "...", "op": "...", "when": "now" } ] } ``` ## Errors | Code | Status | What to do | |---|---|---| | `invalid_input`, `invalid_token`, `rate_limited` | | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |