Retrieve an invoice

curl --request GET \
  --url https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "card",
  "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
  }
}

{
  "statusCode": 401,
  "message": "Invalid API key",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 403,
  "message": "Payment link belongs to another organization",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 404,
  "message": "Payment link not found",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 429,
  "message": "Too many tries in a row. Wait a minute, then try again.",
  "timestamp": "2026-10-31T12:00:00.000Z"
}

GET

gateway

invoices

{invoiceId}

Retrieve an invoice

curl --request GET \
  --url https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.agentaos.ai/api/v1/gateway/invoices/{invoiceId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "card",
  "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
  }
}

{
  "statusCode": 401,
  "message": "Invalid API key",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 403,
  "message": "Payment link belongs to another organization",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 404,
  "message": "Payment link not found",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 429,
  "message": "Too many tries in a row. Wait a minute, then try again.",
  "timestamp": "2026-10-31T12:00:00.000Z"
}

Authorizations

x-api-key

string

header

required

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.

Path Parameters

invoiceId

string<uuid>

required

Invoice UUID.

Response

The invoice, with its earnings breakdown.

string<uuid>

required

invoice_number

string

required

Human-readable, e.g. INV-2026-0142.

transaction_id

string<uuid> | null

required

Linked settled transaction, once paid.

session_id

string | null

required

Linked checkout.

amount

number

required

Currency units.

currency

string

required

payment_token

string

required

What the buyer paid (or will pay) with.

status

enum<string>

required

issued (created, not yet paid), paid (payment settled), or voided.

Available options:

issued,

paid,

voided

fiat_amount

number | null

required

EUR/USD equivalent, for stablecoin payments.

fiat_currency

enum<string> | null

required

Available options:

EUR,

USD,

null

exchange_rate

number | null

required

Rate applied at settlement.

exchange_rate_source

string | null

required

tax_rate

number | null

required

Applied rate, e.g. 19 for 19%.

tax_amount

number | null

required

Currency units.

tax_name

string | null

required

e.g. DE VAT.

tax_inclusive

boolean | null

required

Whether amount already includes tax.

merchant_name

string | null

required

Seller name on the document.

buyer_email

string | null

required

buyer_name

string | null

required

buyer_company

string | null

required

buyer_country

string | null

required

ISO 3166-1 alpha-2.

buyer_vat

string | null

required

tx_hash

string | null

required

On-chain hash, for crypto payments.

issued_at

string<date-time>

required

voided_at

string<date-time> | null

required

created_at

string<date-time>

required

earnings

object | null

required

Present only for a card/bank Merchant-of-Record sale with a linked, settled transaction. null otherwise.

Show child attributes

resolved_amount

number

List rows only (GET /gateway/invoices). The render-ready gross to display: the linked capture's settled earnings when one is available in the invoice's own fiat currency, else fiat_amount, else amount. Already resolved server-side -- never recompute this.

resolved_currency

string

List rows only. Currency for resolved_amount.

org_id

string<uuid>

The business that issued the invoice.

environment

enum<string>

The mode the invoice was issued in.

Available options:

test,

live

customer_id

string<uuid> | null

The buyer's customer record, when there is one.

subscription_id

string<uuid> | null

The subscription this invoice bills, when it bills one.

description

string | null

The line text of the invoice.

due_date

string | null

The due date the merchant set, when they set one.

paid_at

string<date-time> | null

When the invoice was paid. Null while unpaid.

receipt_number

string | null

The receipt number, once a receipt was issued.

receipt_issued_at

string<date-time> | null

When the receipt was issued.

seller_of_record

enum<string> | null

aristokrates_ou when AgentaOS sold as merchant of record; merchant when the business sold directly.

Available options:

merchant,

aristokrates_ou,

null

payment_method

string | null

How the buyer paid, for example card or bank_transfer.

payment_method_brand

string | null

The card brand, for a card payment.

payment_method_last4

string | null

The last 4 digits of the card, for a card payment.

tax_exemption_reason

string | null

Why no VAT was charged (reverse charge, out of scope), when none was.

buyer_address

string | null

The buyer's address as it prints on the invoice.

merchant_address

string | null

The business's address as it prints on the invoice.

merchant_vat

string | null

The business's VAT number as it prints on the invoice.

merchant_wallet

string | null

For a crypto invoice: the business's receiving wallet.

payer_address

string | null

For a crypto payment: the payer's wallet.

payer_metadata

object | null

Who the invoice is for. On an invoice the business created, the bill-to details it entered (for example name, email). On an invoice for a bank-transfer payment, what the payment carried: the payer's name and bank account (iban).

network

string | null

For a crypto invoice: the chain.

chain_id

integer | null

For a crypto invoice: the chain id.

token_address

string | null

For a crypto invoice: the token contract address.

exchange_rate_at

string<date-time> | null

When exchange_rate was taken.

dispute

object | null

The dispute state of the sale behind this invoice, derived on every read. The date is disputedAt on the list and disputed_at on a retrieved invoice.

Show child attributes

amounts

object

The amounts the invoice PDF and the receipt print, in currency units. Render these; do not recompute them.

Show child attributes

SDK

CLI

API Reference

Retrieve an invoice

Authorizations

Path Parameters

Response