> ## Documentation Index > Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json get /v1/organization/invoices/{id} openapi: 3.1.0 info: title: VEXiON cards Public API description: >- ## Rate limiting Two independent layers, checked in this order: 1. **Per-IP throttle (pre-authentication).** Applied to every `/v1` request BEFORE the API key is checked, keyed on the caller's IP address: - **600 requests/minute** per IP - a flood ceiling, `429 rate_limit_error` / `rate_limited`. - **20 failed authentications per 15 minutes** per IP - a key-guessing ceiling. Only responses that are `401` (missing/invalid/revoked key) count against this ceiling; a `403` from a valid key that simply lacks a scope does not. `429 rate_limit_error` / `too_many_failed_attempts`. Both ceilings send `Retry-After` (seconds). 2. **Per-key, per-bucket limiter (post-authentication).** Documented per endpoint (see each operation's `429` response and the `rate_limit` field on the API Key resource) - e.g. 60/min default, 120/min for transactions, plus the notification-broadcast and lookup-filter buckets described on their own endpoints. ### Rate-limit response headers Every rate-limited response carries the legacy `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` family (the last is an **epoch timestamp**) AND the IETF standards-track headers, side by side: - `RateLimit-Policy: "";q=;w=` - the static policy for the bucket that was hit. - `RateLimit: "";r=;t=` - live state. **`t` is a DURATION (seconds remaining), not the epoch timestamp `X-RateLimit-Reset` carries - the two are never the same value.** version: 1.0.0 servers: - url: https://api.vexioncards.one description: Production - url: https://migration.api.vexioncards.one description: Sandbox security: - apiKey: [] tags: - name: Customers - name: Cards - name: Transactions - name: Notifications - name: Locations - name: Products - name: API keys - name: Organization - name: Webhook endpoints - name: Events - name: Custom fields - name: Team members - name: Icons paths: /v1/organization/invoices/{id}: get: tags: - Organization summary: Retrieve an invoice description: >- 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. operationId: getOrganizationInvoice parameters: - name: id in: path description: Invoice identifier (`inv_` prefix). required: true example: inv_01HXYZINV001 schema: type: string pattern: ^inv_[A-Za-z0-9]+$ responses: '200': description: Invoice. content: application/json: schema: $ref: '#/components/schemas/Invoice' examples: Invoice: summary: Full DTO with fresh pdf_url value: 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 headers: {} '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: API key lacks the `organization:read` scope (added 2026-07-27). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Resource not found. References to another organization also return 404, never 403. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '429': description: Rate limited - respect Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. Retry-safe on idempotent calls. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: api_error code: internal_error message: >- An internal error occurred. The request may be retried with the same Idempotency-Key. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 examples: Http 500 default: summary: Http 500 default value: error: type: api_error code: internal_error message: >- An internal error occurred. The request may be retried with the same Idempotency-Key. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 headers: {} deprecated: false components: schemas: Invoice: type: object description: >- 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. required: - id - object - status - paid - amount - currency - issued_at - created_at properties: id: type: string pattern: ^inv_[A-Za-z0-9]+$ description: Invoice identifier (`inv_` prefix). example: inv_01HXYZINV001 object: type: string const: invoice description: Always `"invoice"`. number: type: - string - 'null' description: >- Invoice number as issued. Null while the invoice has not been issued yet (`requires_billing_details`, `failed`). example: '2026000147' status: type: string enum: - paid - open - pending - requires_billing_details - failed - refunded - credit_note description: >- 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`. example: paid paid: type: boolean description: Convenience flag aligned with `status`. example: true amount: type: number description: >- 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 amount_paid: type: number description: >- 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: type: number description: >- VAT portion, MAJOR units (same documented exception as `amount` above). example: 8.42 vat_rate: type: number description: VAT rate percentage applied. example: 23 reverse_charge: type: boolean description: >- True for intra-EU reverse-charge invoices (VAT 0, customer self-accounts). example: false currency: type: string description: >- 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 presentment_currency: type: - string - 'null' description: >- Customer-facing currency for non-EUR adaptive pricing. Null when invoiced directly in EUR. presentment_amount: type: - number - 'null' description: Amount in `presentment_currency`. Null when not applicable. payment_method: type: string enum: - card - bank_transfer description: Neutral channel descriptor - independent of any payment processor. example: card issued_at: type: integer description: >- Unix seconds of invoice issuance (when the numbered document was generated). example: 1780460353 paid_at: type: - integer - 'null' description: Unix seconds of settlement. Null while unpaid. example: 1780460355 pdf_url: type: string format: uri description: >- 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: type: number description: >- Refunded portion, MAJOR units (same documented exception as `amount` above). 0 when never refunded. example: 0 refunded_at: type: - integer - 'null' description: Unix seconds of the refund. Null when never refunded. refund_reason: type: - string - 'null' description: Merchant-visible refund reason. Null when never refunded. corrects_invoice_id: type: - string - 'null' description: 'On credit notes: the original invoice this document corrects.' corrected_by_invoice_id: type: - string - 'null' description: 'On originals: the credit note that corrected this invoice.' location_id: type: - string - 'null' description: >- Populated for per-location franchise invoices. Null for org-level invoices. created_at: type: integer description: Unix seconds. example: 1780460353 Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - idempotency_error - api_error code: type: string message: type: string retry_after: type: integer description: >- Seconds to wait before retrying. Present on rate-limit (429) and idempotency-key-in-use (409) errors; mirrors the `Retry-After` HTTP header. Absent on error types that carry no retry guidance. example: 5 param: type: - string - 'null' request_id: type: string doc_url: type: string format: uri field_errors: type: array description: >- Per-field errors on a 422. At most 100 entries: a request with more errors gets the first 100. items: type: object properties: param: type: string code: type: string message: type: string expected_currency: type: string description: >- On `currency_mismatch`: the business currency the request must use. Absent on every other field error. description: >- The error payload: type (category), code (machine-readable), message (human-readable), retry_after (seconds, on rate-limit/idempotency-in-use errors only), param (offending field), request_id, doc_url, field_errors[]. description: >- Standard error envelope. Branch on `error.code`; include `error.request_id` in support requests. See the Errors guide. securitySchemes: apiKey: type: http scheme: bearer description: >- Your secret API key as a Bearer token: `Authorization: Bearer vxn_sk_...`. Keys are created and scoped in the dashboard - see [Authentication](/api-reference/introduction#authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.