Get Invoice

Retrieve an invoice with its payment history and outstanding balance.

GET /v1/invoice/{id}

cURL

curl 'https://api.stateset.com/api/v1/invoices/inv_1234567890' \
  -H 'Authorization: Bearer <token>'

200

{
  "invoice_id": "inv_1234567890",
  "status": "sent",
  "total_amount": { "value": "12000.00", "denom": "ssusd" },
  "amount_paid": { "value": "5000.00", "denom": "ssusd" },
  "balance_due": { "value": "7000.00", "denom": "ssusd" },
  "payments": [
    {
      "amount": { "value": "5000.00", "denom": "ssusd" },
      "paid_at": "2024-06-25T12:05:00Z",
      "transaction_hash": "0x742d35Cc6634C0532925a3b8D097C00D4dfece08"
    }
  ]
}

Overview

Returns the invoice and everything that has been paid against it. Because invoices accept partial payments, status alone does not tell you what is owed — read balance_due.

Path

id · string · required

The invoice identifier, e.g. inv_1234567890.

Response

invoice_id · string · required

Invoice identifier.

status · string · required

draft, sent, viewed, paid, overdue, or voided.

total_amount · object · required

Total invoiced, as a { value, denom } pair.

amount_paid · object · required

Total received to date across all payments.

balance_due · object · required

Remaining balance. This is the authoritative figure — a partially_paid invoice and an unpaid one are both outstanding, and only this field says by how much.

payments · array · required

Every payment applied, most recent first. Each entry carries its amount, settlement time, and transaction hash.

cURL

curl 'https://api.stateset.com/api/v1/invoices/inv_1234567890' \
  -H 'Authorization: Bearer <token>'

200

{
  "invoice_id": "inv_1234567890",
  "status": "sent",
  "total_amount": { "value": "12000.00", "denom": "ssusd" },
  "amount_paid": { "value": "5000.00", "denom": "ssusd" },
  "balance_due": { "value": "7000.00", "denom": "ssusd" },
  "payments": [
    {
      "amount": { "value": "5000.00", "denom": "ssusd" },
      "paid_at": "2024-06-25T12:05:00Z",
      "transaction_hash": "0x742d35Cc6634C0532925a3b8D097C00D4dfece08"
    }
  ]
}

Reconciling? Assert total_amount − amount_paid == balance_due rather than trusting any one field. A mismatch means a payment settled between your read and your calculation — re-read rather than adjusting.

Related

• List Invoices
• Pay Invoice
• Void Invoice
• Factor Invoice — get paid before the buyer pays