Retrieve an invoice

Returns a single invoice with a freshly signed pdf_url (1-hour TTL). Download promptly; the url itself expires per S3’s own presigned-URL rules - an expired link returns S3’s own 403 Forbidden (an XML body, not the VEXiON JSON error envelope, since the request goes straight to S3 and never reaches this API). There is no dedicated VEXiON error code for this; re-fetch the invoice via this endpoint for a fresh pdf_url.

Credit notes point at the original via corrects_invoice_id; corrected originals carry corrected_by_invoice_id. Walk the pair to reconstruct the correction chain for accounting exports.

Scope: organization:read. Added 2026-07-27 (owner-approved versioned API change). This endpoint used to require no scope at all: any valid key for the organization, whatever scopes it carried, could read this organization’s invoice history, including amounts, VAT, payment method and refunds - a key minted only for, say, notifications:send could still read it. That gap is now closed. Existing keys minted before 2026-07-27 were backfilled with organization:read so no working integration broke when enforcement landed.

GET /v1/organization/invoices/{id}

Retrieve an invoice

cURL

curl --request GET \
  --url https://api.vexioncards.one/v1/organization/invoices/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "inv_01HXYZINV001",
  "object": "invoice",
  "number": "2026000147",
  "status": "paid",
  "paid": true,
  "amount": 45,
  "amount_paid": 45,
  "vat_amount": 8.42,
  "vat_rate": 23,
  "reverse_charge": false,
  "currency": "EUR",
  "presentment_currency": null,
  "presentment_amount": null,
  "payment_method": "card",
  "issued_at": 1780460353,
  "paid_at": 1780460355,
  "pdf_url": "https://files.vexioncards.one/invoices/2026/VEX-2026000147.pdf?sig=abc&exp=1780464000",
  "refunded_amount": 0,
  "refunded_at": null,
  "refund_reason": null,
  "corrects_invoice_id": null,
  "corrected_by_invoice_id": null,
  "location_id": null,
  "created_at": 1780460353
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Path Parameters

id · string · required

Invoice identifier (inv_ prefix).

Pattern: ^inv_[A-Za-z0-9]+$

Response

200

application/json

Invoice.

An issued subscription invoice. Amounts are in MAJOR units of currency (this resource mirrors the human invoice document - unlike loyalty mechanics, which use minor units). PDF download via short-TTL signed URL.

id · string · required

Invoice identifier (inv_ prefix).

Pattern: ^inv_[A-Za-z0-9]+$

Example:

"inv_01HXYZINV001"

object · string · required

Always "invoice".

Allowed value: "invoice"

status · enum<string> · required

Invoice lifecycle. requires_billing_details = issuance blocked until the merchant completes billing identity. credit_note = a correcting document pointing at the original via corrects_invoice_id.

Available options: paid, open, pending, requires_billing_details, failed, refunded, credit_note

Example:

"paid"

paid · boolean · required

Convenience flag aligned with status.

Example:

true

amount · number · required

Gross total in MAJOR units (45.0 = €45.00) - the Invoice resource is the ONE documented exception to the minor-units convention: it mirrors the human invoice document (see doc conventions R4).

Example:

45

currency · string · required

ISO 4217 invoice currency: EUR, or CZK for a business billed on the fixed Czech crown price list. Independent of the business currency of your loyalty cards.

Example:

"EUR"

issued_at · integer · required

Unix seconds of invoice issuance (when the numbered document was generated).

Example:

1780460353

created_at · integer · required

Unix seconds.

Example:

1780460353

number · string | null

Invoice number as issued. Null while the invoice has not been issued yet (requires_billing_details, failed).

Example:

"2026000147"

amount_paid · number

Amount actually charged to the payment method, MAJOR units (same documented exception as amount above). NOTE: an invoice fully covered by account credit is paid with amount_paid: 0 - check status, not this number, for settlement.

Example:

45

vat_amount · number

VAT portion, MAJOR units (same documented exception as amount above).

Example:

8.42

vat_rate · number

VAT rate percentage applied.

Example:

23

reverse_charge · boolean

True for intra-EU reverse-charge invoices (VAT 0, customer self-accounts).

Example:

false

presentment_currency · string | null

Customer-facing currency for non-EUR adaptive pricing. Null when invoiced directly in EUR.

presentment_amount · number | null

Amount in presentment_currency. Null when not applicable.

payment_method · enum<string>

Neutral channel descriptor - independent of any payment processor.

Available options: card, bank_transfer

Example:

"card"

paid_at · integer | null

Unix seconds of settlement. Null while unpaid.

Example:

1780460355

pdf_url · string<uri>

Signed download URL for the PDF (1-hour TTL - fetch fresh from this endpoint when the link expires; do not store the URL, store the invoice id).

Example:

"https://files.vexioncards.one/invoices/2026/VEX-2026000147.pdf?sig=abc&exp=1780464000"

refunded_amount · number

Refunded portion, MAJOR units (same documented exception as amount above). 0 when never refunded.

Example:

0

refunded_at · integer | null

Unix seconds of the refund. Null when never refunded.

refund_reason · string | null

Merchant-visible refund reason. Null when never refunded.

corrects_invoice_id · string | null

On credit notes: the original invoice this document corrects.

corrected_by_invoice_id · string | null

On originals: the credit note that corrected this invoice.

location_id · string | null

Populated for per-location franchise invoices. Null for org-level invoices.