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 |
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.
| Field | Type | Required |
|---|
invoice_id | string (uuid) | yes |
Example
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 |
{
"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. |