Semantics
Read-only. Returns the invoice's status, amount, currency, due date, the contact it was issued to, and the public token URL where the customer can view and pay it via Stripe Checkout. The public token URL is shareable.
Invariants
- Pure read. No state change.
- Returns the same payload for repeat calls (until the invoice itself is updated by other means).
- `payment_url` is provider-issued and may rotate. Re-fetch instead of caching long-term.
When to use
Whenever an agent needs to confirm payment status, share a payable link with the customer, or display invoice details mid-conversation.
Input schema
{
"type": "object",
"required": [
"invoice_number"
],
"properties": {
"agent_vendor": {
"type": "string"
},
"invoice_number": {
"type": "string",
"description": "The provider-issued invoice number, e.g. 'INV-0042'."
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"enum": [
"unknown_invoice",
"invalid_input"
],
"type": "string"
},
"amount": {
"type": "number"
},
"due_at": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"draft",
"issued",
"paid",
"overdue",
"cancelled"
],
"type": "string"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
}
}
},
"currency": {
"type": "string"
},
"issued_at": {
"type": "string",
"format": "date-time"
},
"invoice_id": {
"type": "string"
},
"payment_url": {
"type": "string",
"format": "uri"
},
"invoice_number": {
"type": "string"
}
}
}