> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentaos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve an invoice > Same fields as the list, plus `earnings`: a fee/VAT/net breakdown, present only for a card/bank Merchant-of-Record sale with a linked, settled transaction. `null` otherwise (crypto sales, or a not-yet-paid `issued` invoice). ## OpenAPI ````yaml GET /gateway/invoices/{invoiceId} openapi: 3.1.0 info: title: AgentaOS Gateway API version: 1.0.0 description: >- The AgentaOS REST API: payment links, checkouts, subscriptions, customers, invoices, and the unified transactions feed. This is the same API the TypeScript SDK (`@agentaos/pay`) and the `agenta` CLI call underneath. ## Money model - **Decimal currency units (`number`)**: a plain `amount` field (on a create body, a Payment Link, a Checkout's `amount_override`, or an Invoice's `amount`/`fiat_amount`/`tax_amount`) is in currency units. `49.99` means EUR 49.99, never cents. - **Integer minor units (`number`)**: exactly one field breaks that rule: `unitAmountMinor` on a Subscription. It is an integer count of the smallest currency unit (`1999` means EUR 19.99), named with a `Minor` suffix specifically so it is never confused with a plain `amount`. The `money` object on Transactions and the `earnings` object on a retrieved Invoice are also integer minor units, computed server-side. - **String, on webhooks**: the `amount` inside a webhook payload's `data` object is a string (e.g. `"49.99"`), since JSON numbers silently drop trailing zeros and this value must round-trip exactly for accounting. ## Naming convention Most response fields mirror the underlying database column and are `snake_case` (`created_at`, `seller_mode`, `buyer_email`, ...). A small number of computed convenience fields are camelCase with no snake_case equivalent: `checkoutUrl` on Checkouts and Payment Links, `sellerMode` on Payment Links specifically, `money` on Transactions, and `earnings` on a single retrieved Invoice. Two resources (Subscriptions and Customers) are fully camelCase end to end. ## Pagination Every list endpoint takes `limit` and `offset` and returns `{ items, total, hasMore }`. `hasMore` is computed server-side (`offset + items.length < total`); never derive it client-side. contact: name: AgentaOS url: https://agentaos.ai license: name: Proprietary url: https://agentaos.ai servers: - url: https://api.agentaos.ai/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Payment Links description: >- Reusable, shareable payment products: a fixed amount and description behind one URL. - name: Checkouts description: >- One attempt to collect one payment, standalone or built from a payment link. Wire path is `/gateway/sessions`; the SDK and CLI call this resource "checkout". - name: Subscriptions description: >- Merchant-side read and management surface for recurring plans. Created automatically when a buyer pays a `type: subscription` payment link. - name: Customers description: 'Read-only surface: everyone who has paid you or been sent an invoice.' - name: Invoices description: >- Every checkout issues an invoice. List, retrieve, void, export, and download PDFs/receipts. - name: Transactions description: >- The unified activity feed: every inbound payment and outbound send, across every rail, in one list. paths: /gateway/invoices/{invoiceId}: get: tags: - Invoices summary: Retrieve an invoice description: >- Same fields as the list, plus `earnings`: a fee/VAT/net breakdown, present only for a card/bank Merchant-of-Record sale with a linked, settled transaction. `null` otherwise (crypto sales, or a not-yet-paid `issued` invoice). operationId: getInvoice parameters: - $ref: '#/components/parameters/InvoiceId' responses: '200': description: The invoice, with its earnings breakdown. content: application/json: schema: $ref: '#/components/schemas/InvoiceDetail' examples: default: $ref: '#/components/examples/InvoiceDetailExample' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: InvoiceId: name: invoiceId in: path required: true description: Invoice UUID. schema: type: string format: uuid schemas: InvoiceDetail: allOf: - $ref: '#/components/schemas/Invoice' - type: object properties: earnings: anyOf: - $ref: '#/components/schemas/Earnings' - type: 'null' description: >- Present only for a card/bank Merchant-of-Record sale with a linked, settled transaction. null otherwise. required: - earnings Invoice: type: object additionalProperties: true properties: id: type: string format: uuid invoice_number: type: string description: Human-readable, e.g. INV-2026-0142. transaction_id: type: - string - 'null' format: uuid description: Linked settled transaction, once paid. session_id: type: - string - 'null' description: Linked checkout. amount: type: number description: Currency units. currency: type: string payment_token: type: string description: What the buyer paid (or will pay) with. status: type: string enum: - issued - paid - voided description: issued (created, not yet paid), paid (payment settled), or voided. fiat_amount: type: - number - 'null' description: EUR/USD equivalent, for stablecoin payments. fiat_currency: type: - string - 'null' enum: - EUR - USD - null exchange_rate: type: - number - 'null' description: Rate applied at settlement. exchange_rate_source: type: - string - 'null' tax_rate: type: - number - 'null' description: Applied rate, e.g. 19 for 19%. tax_amount: type: - number - 'null' description: Currency units. tax_name: type: - string - 'null' description: e.g. DE VAT. tax_inclusive: type: - boolean - 'null' description: Whether amount already includes tax. merchant_name: type: - string - 'null' description: Seller name on the document. buyer_email: type: - string - 'null' buyer_name: type: - string - 'null' buyer_company: type: - string - 'null' buyer_country: type: - string - 'null' description: ISO 3166-1 alpha-2. buyer_vat: type: - string - 'null' tx_hash: type: - string - 'null' description: On-chain hash, for crypto payments. issued_at: type: string format: date-time voided_at: type: - string - 'null' format: date-time created_at: type: string format: date-time required: - id - invoice_number - transaction_id - session_id - amount - currency - payment_token - status - fiat_amount - fiat_currency - exchange_rate - exchange_rate_source - tax_rate - tax_amount - tax_name - tax_inclusive - merchant_name - buyer_email - buyer_name - buyer_company - buyer_country - buyer_vat - tx_hash - issued_at - voided_at - created_at Earnings: type: object description: >- Merchant-only fee/VAT/net breakdown, integer minor units in `currency`. grossMinor is your ex-VAT sale base (agentaosFeeMinor + netMinor); the buyer paid grossMinor + vatMinor. properties: currency: type: string grossMinor: type: integer agentaosFeeMinor: type: integer vatMinor: type: integer netMinor: type: integer required: - currency - grossMinor - agentaosFeeMinor - vatMinor - netMinor Error: type: object description: >- Every non-2xx response is JSON in this shape. Every response (success or error) also carries an `x-request-id` response header; send that header on your request to have your own id echoed back, otherwise the server mints one. On errors the same id is repeated in the `requestId` body field. properties: statusCode: type: integer description: Same as the HTTP status code. message: description: >- Human-readable. A validation failure (400) returns an array of per-field messages instead of one string. anyOf: - type: string - type: array items: type: string errors: type: array description: >- Present on 400 validation failures: one entry per invalid field. The flat human-readable strings stay in `message` for back-compat; this is the machine-readable, per-field view. items: type: object properties: field: type: string description: >- Name of the invalid field, dot-notated for nested properties (e.g. `checkoutFields.0.type`). message: type: string description: Validation messages for that field, joined with `, `. required: - field - message requestId: type: string description: >- Correlation id, identical to the `x-request-id` response header. Include it when contacting support. On success it is available on the header only, not the body. timestamp: type: string format: date-time required: - statusCode - message - timestamp examples: InvoiceDetailExample: value: id: b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e transaction_id: 8c7d6e5f-4a3b-2c1d-0e9f-8a7b6c5d4e3f org_id: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d session_id: mZrESFyR7RC9RPsJfZCVkg invoice_number: INV-2026-0142 amount: 49.99 currency: EUR payment_token: EURC description: 'Order #123' tx_hash: null network: stripe fiat_amount: 49.99 fiat_currency: EUR exchange_rate: 1 exchange_rate_source: 1:1 peg status: paid issued_at: '2026-08-06T12:00:00.000Z' voided_at: null created_at: '2026-08-06T12:00:00.000Z' merchant_name: Acme Inc buyer_email: john@example.com buyer_country: DE buyer_name: John Doe buyer_company: null buyer_vat: null tax_rate: null tax_amount: null tax_name: null tax_inclusive: null earnings: currency: EUR grossMinor: 4999 agentaosFeeMinor: 215 vatMinor: 0 netMinor: 4784 responses: Unauthorized: description: Missing or invalid `x-api-key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 401 message: Invalid API key timestamp: '2026-08-06T12:00:00.000Z' Forbidden: description: The key is valid but the resource belongs to a different organization. content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 403 message: Payment link belongs to another organization timestamp: '2026-08-06T12:00:00.000Z' NotFound: description: >- Resource not found (or not visible to your key; the two are not distinguished). content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 404 message: Payment link not found timestamp: '2026-08-06T12:00:00.000Z' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your secret key, from app.agentaos.ai -> Settings -> Developers -> API Keys. The key's prefix is both its identity and its environment: `sk_test_...` (sandbox, free, no verification) or `sk_live_...` (real money, requires business verification). A missing or invalid key returns 401. ````