> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mitu.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server. # List invoices GET https://api.mitu.ai/v1/invoices List your invoices. Reference: https://docs.mitu.ai/api-reference/invoices/list-invoices ## Authentication - `x-api-key` header (required) — Account API key used to authenticate server-side requests. Use the credentials issued for the same environment as the API base URL. ## Servers - `https://api.mitu.ai` (Production, default) - `https://sandbox-api.mitu.ai` (Sandbox) ## Request ### Query parameters - `status` (enum, optional) — Filter by invoice status. - Allowed values: `draft`, `sent`, `viewed`, `settling`, `paid`, `overdue`, `cancelled` - `recipientId` (string, optional) — Return invoices addressed to a specific recipient. - `recipientReference` (string, optional) — Return only invoices whose recipient has this reference. - `limit` (integer, optional, default: 20) — Maximum number of records to return. - `cursor` (string, optional) — Cursor returned as `next_cursor` from the previous response. Omit for the first request. ## Response ### 200 Invoices retrieved successfully. - `message` (string, required) - `data` (list of Invoice, required) - `meta` (PaginationMeta, required) ## Errors ### 401 Unauthorized Error Authentication failed because the API key is missing or invalid. - `message` (string, required) — Human-readable description of the error. ### 403 Forbidden Error The authenticated account is not allowed to perform this action. - `message` (string, required) — Human-readable description of the error. ### 422 Unprocessable Entity Error One or more request fields are invalid. - `message` (string, required) - `errors` (list of ValidationErrorDetail, required) ### 429 Too Many Requests Error Too many requests were sent in a short period. - `message` (string, required) — Human-readable description of the error. ### 500 Internal Server Error An unexpected error occurred while processing the request. - `message` (string, required) — Human-readable description of the error. ## Types ### Invoice Response fields are snake_case; request fields are camelCase. - `id` (string, optional) - `invoice_number` (string, optional, nullable) - `status` (enum, optional) - Allowed values: `draft`, `sent`, `viewed`, `settling`, `paid`, `overdue`, `cancelled` - `recipient` (Recipient, optional, nullable) — Who the invoice is addressed to. Still returned after the recipient is deleted. - `description` (string, optional, nullable) - `line_items` (list of InvoiceLineItem, optional) - `subtotal` (string, optional) — The sum of the line items. - `tax_amount` (string, optional) - `discount_amount` (string, optional) - `amount` (string, optional) — The total the payer is asked for, `subtotal` plus `tax_amount` minus `discount_amount`. - `currency` (string, optional) - `url` (PayUrl, optional) — The two ways to pay one resource. `checkout` is the page a person opens; `agent` is the 402-protected route an AI agent calls. They are not interchangeable — an agent given the checkout URL receives HTML instead of a payment challenge. - `due_at` (datetime, optional, nullable) - `sent_at` (datetime, optional, nullable) - `viewed_at` (datetime, optional, nullable) - `paid_at` (datetime, optional, nullable) - `created_at` (datetime, optional) ### PaginationMeta - `total` (integer, required) — Total number of records matching the request. - `limit` (integer, required) — Maximum number of records requested for this response. - `has_more` (boolean, required) — Whether more records are available after this response. - `next_cursor` (string, required, nullable) — Cursor to pass in the next request. `null` when there are no more records. ### ValidationErrorDetail - `field` (string, required) — Field that failed validation. - `message` (string, required) — Description of the validation problem. ### Recipient - `id` (string, optional) - `name` (string, optional) - `email` (string, optional, nullable) - `phone` (string, optional, nullable) - `reference` (string, optional, nullable) - `created_at` (datetime, optional) ### InvoiceLineItem - `name` (string, required) - `quantity` (integer, required) - `amount` (double, required) - `description` (string, optional) ### PayUrl The two ways to pay one resource. `checkout` is the page a person opens; `agent` is the 402-protected route an AI agent calls. They are not interchangeable — an agent given the checkout URL receives HTML instead of a payment challenge. - `checkout` (string, required) — The hosted checkout a person opens. - `agent` (string, required) — The route an AI agent pays programmatically. ## Examples **Response** ```json { "message": "Invoices retrieved successfully", "data": [ { "id": "inv_4k2m9x7ptw3c", "invoice_number": "INV-2026-0041", "status": "draft", "recipient": { "id": "rcp_ds9hazr8jd3l", "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+2348012345678", "reference": "user_42", "created_at": "2026-09-11T15:00:34.915Z" }, "description": "September retainer", "line_items": [ { "name": "Large pizza", "quantity": 2, "amount": 12.5, "description": "Pepperoni, thin crust" } ], "subtotal": "1500.00", "tax_amount": "0.00", "discount_amount": "0.00", "amount": "1500.00", "currency": "USD", "url": { "checkout": "https://mitu.ai/pay/pay_n8d7piu1yc6h", "agent": "https://api.mitu.ai/pay/pay_n8d7piu1yc6h" }, "due_at": "2026-09-30T23:59:59.000Z", "sent_at": "2026-09-11T15:00:34.915Z", "viewed_at": "2026-09-11T15:00:34.915Z", "paid_at": "2026-09-11T15:00:34.915Z", "created_at": "2026-09-11T15:00:34.915Z" } ], "meta": { "total": 84, "limit": 20, "has_more": true, "next_cursor": "cur_01HXYZ9999XXXXXX" } } ``` **SDK Code** ```python import requests url = "https://api.mitu.ai/v1/invoices" querystring = {"recipientId":"rcp_ds9hazr8jd3l","recipientReference":"user_42"} headers = {"x-api-key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.mitu.ai/v1/invoices?recipientId=rcp_ds9hazr8jd3l&recipientReference=user_42")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```