> ## 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 your organization > **Scope: `organization:read`.** Added 2026-07-27 (owner-approved versioned API change, v1 scope registry reopened from twelve to thirteen scopes) - this endpoint used to require no scope at all, so any valid key for the organization could read it regardless of its granted scopes; that gap is now closed. Existing keys minted before 2026-07-27 were backfilled with this scope so no working integration broke when enforcement landed. Read-only self-introspection of the calling key's organization: plan, effective caps with live usage, billing details, account state, and email preferences. ## Caps mirror enforcement `caps..used` is computed by the SAME count queries the in-app plan-limit guard uses - the number you read here is the number that gets enforced. `limit: null` means unlimited. Use this before bulk operations: if `caps.customers.used` is at 95% of `limit`, a bulk import will start failing with `403 plan_limit_reached` partway through. ## caps.locations breakdown Added 2026-07-27, additive: alongside the existing `limit`/`used`, `caps.locations.paid` / `.bonus` / `.delegated_used` split the same location rows into paid-quota, admin-granted-bonus, and manager-billed-delegated buckets - see the `OrganizationCaps` schema for the exact definitions. ## Account state Check `account_state` in health probes: anything other than `active` means writes may be restricted (`paused` = read-only cards, `locked` = compliance hold, etc.). ## OpenAPI ````yaml /openapi.json get /v1/organization 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: get: tags: - Organization summary: Retrieve your organization description: >- **Scope: `organization:read`.** Added 2026-07-27 (owner-approved versioned API change, v1 scope registry reopened from twelve to thirteen scopes) - this endpoint used to require no scope at all, so any valid key for the organization could read it regardless of its granted scopes; that gap is now closed. Existing keys minted before 2026-07-27 were backfilled with this scope so no working integration broke when enforcement landed. Read-only self-introspection of the calling key's organization: plan, effective caps with live usage, billing details, account state, and email preferences. ## Caps mirror enforcement `caps..used` is computed by the SAME count queries the in-app plan-limit guard uses - the number you read here is the number that gets enforced. `limit: null` means unlimited. Use this before bulk operations: if `caps.customers.used` is at 95% of `limit`, a bulk import will start failing with `403 plan_limit_reached` partway through. ## caps.locations breakdown Added 2026-07-27, additive: alongside the existing `limit`/`used`, `caps.locations.paid` / `.bonus` / `.delegated_used` split the same location rows into paid-quota, admin-granted-bonus, and manager-billed-delegated buckets - see the `OrganizationCaps` schema for the exact definitions. ## Account state Check `account_state` in health probes: anything other than `active` means writes may be restricted (`paused` = read-only cards, `locked` = compliance hold, etc.). operationId: getOrganization parameters: [] responses: '200': description: Organization. content: application/json: schema: $ref: '#/components/schemas/Organization' examples: Active PRO organization: summary: Full self-introspection value: id: org_01HXYZORG001 object: organization name: Demo Bakery s.r.o. country: SK default_currency: EUR default_language: sk account_state: active plan: tier: pro subscription_interval: monthly cancel_at_period_end: false current_period_ends_at: 1785283200 caps: cards: limit: null used: 7 customers: limit: null used: 1832 locations: limit: 3 used: 2 paid: limit: 3 used: 2 bonus: limit: 1 used: 0 delegated_used: 0 team_members: limit: 50 used: 4 pos_integration: true analytics_export: true automations: true physical_gift_cards: true gift_card_online_sales: true billing_details: company_name: Demo Bakery s.r.o. tax_id: '12345678' vat_id: '1020304050' vat_id_intra_eu: SK1020304050 address: line1: Obchodná 12 city: Bratislava postal_code: '81106' country: SK email: billing@demo-bakery.example phone: '+421900000000' email_preferences: onboarding: true feature_adoption: true achievements: true reports: true gift_card_sales: false created_at: 1757664000 updated_at: 1782561600 headers: {} '400': description: Malformed body or missing required field. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '403': description: API key lacks the `organization:read` scope (added 2026-07-27). content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '429': description: Per-minute or per-day rate limit exceeded. Respect Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '500': description: Server error. Retry-safe on idempotent calls. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} deprecated: false components: schemas: Organization: type: object description: >- Read-only self-introspection of YOUR organization: plan, effective caps with live usage, billing details, account state, email preferences. `GET` only - nothing on this resource is writable via API. The `id` is an opaque support reference; `organization_id` never appears on any other resource body (the API key selects the organization). required: - id - object - name - country - default_currency - default_language - account_state - plan - caps - created_at properties: id: type: string pattern: ^org_[A-Za-z0-9]+$ description: >- Opaque id for support reference ONLY - never accepted as input anywhere. example: org_01HXYZORG001 object: type: string const: organization description: Always `"organization"`. name: type: string description: Display name. example: Demo Bakery s.r.o. country: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2. example: SK default_currency: type: string description: >- ISO 4217. The one currency of the business: all monetary card mechanics, transactions and analytics use it. It is set from the country of the first location and locked after the first transaction, customer balance or gift card purchase. Your VEXiON subscription is always billed in EUR. See [Money and currency](/api-reference/money-and-currency). example: EUR default_language: type: string enum: - sk - cs - en - de description: Fallback language for passes + notifications. example: sk account_state: type: string enum: - pending_activation - awaiting_claim - active - paused - cancelling - cancelled - locked description: |- Account lifecycle: - `pending_activation` - created, no subscription yet - `awaiting_claim` - provisioned by sales, owner hasn't claimed - `active` - fully operational - `paused` - merchant-paused (free); cards read-only - `cancelling` - wind-down until period end - `cancelled` - read-only retention window - `locked` - admin/compliance hold example: active plan: $ref: '#/components/schemas/OrganizationPlan' caps: $ref: '#/components/schemas/OrganizationCaps' billing_details: $ref: '#/components/schemas/BillingDetails' email_preferences: type: object description: >- Merchant-controlled email topic opt-ins. Transactional email (billing, security) always sends. **Three of these five are enforced today: `onboarding`, `feature_adoption` and `achievements`.** Enforcement works by matching the flag name against a campaign's topic, and those are the only three topics any campaign declares, so setting one to `false` genuinely stops those emails. **`reports` and `gift_card_sales` are RESERVED and not yet honoured.** No campaign declares either topic, and no gift-card sender consults the flag, so setting them to `false` is accepted and stored but suppresses nothing. They are kept in the contract because they are already stored on existing organizations; treat them as forward declarations rather than working switches, and do not rely on either to stop mail. properties: onboarding: type: boolean description: Setup guidance and activation tips. feature_adoption: type: boolean description: New features and how to use them. achievements: type: boolean description: Milestones and celebration emails. reports: type: boolean description: Periodic performance reports. gift_card_sales: type: boolean description: Gift card sales notifications. example: onboarding: true feature_adoption: true achievements: true reports: true gift_card_sales: true created_at: type: integer description: Unix seconds. example: 1757664000 updated_at: type: integer description: Unix seconds of last change. example: 1782561600 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) errors and on the retryable 409 conflicts (`idempotency_key_in_use`, `create_in_progress`, `concurrent_update`); 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 errors and retryable 409 conflicts 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. OrganizationPlan: type: object description: >- Subscription snapshot. The tier/interval enum is closed - new intervals ship as documented additive changes. properties: tier: type: string enum: - one - pro - free description: VEXiON ONE (flat), VEXiON PRO (per-location), or free (comped). example: pro subscription_interval: type: - string - 'null' enum: - monthly - quarterly - annual - null description: >- Billing interval. Null when no active subscription (e.g. comped accounts). example: monthly cancel_at_period_end: type: boolean description: True when a cancellation is scheduled for period end. example: false current_period_ends_at: type: - integer - 'null' description: >- Unix seconds when the current billing period ends. Null when no subscription. example: 1785283200 OrganizationCaps: type: object description: >- Effective plan caps with live usage. Numeric caps are `{limit, used}` where `limit: null` means unlimited. `used` is computed by the SAME count queries the in-app plan-limit guard uses, so the public number always matches the enforced number. Boolean entitlements reflect the merged plan defaults + per-org overrides. properties: cards: type: object description: Card template cap. properties: limit: type: - integer - 'null' description: Null = unlimited. used: type: integer example: limit: null used: 7 customers: type: object description: Enrolled customer cap. properties: limit: type: - integer - 'null' used: type: integer example: limit: null used: 1832 locations: type: object description: >- Location cap. Per-org location quota wins over plan default when present. `paid` / `bonus` / `delegated_used` (added 2026-07-27) are an ADDITIVE breakdown of the same underlying location rows this cap's own `used` counts: `paid.used` is billable locations consuming a paid quota slot, `bonus.used` is admin-granted free locations consuming a bonus slot, and `delegated_used` is born-delegated locations billed to a manager's own subscription rather than to this organization's paid/bonus slots at all. `limit` and `used` are unchanged by this addition. properties: limit: type: - integer - 'null' used: type: integer paid: type: object description: >- Paid quota slots: locationQuota.paid vs. billable, non-free locations currently consuming one. properties: limit: type: - integer - 'null' used: type: integer example: limit: 3 used: 2 bonus: type: object description: >- Admin-granted free quota slots: locationQuota.bonus vs. free, non-online locations currently consuming one. properties: limit: type: - integer - 'null' used: type: integer example: limit: 1 used: 0 delegated_used: type: integer description: >- Born-delegated locations (billing.billingType 'delegated') billed to a manager's own subscription, not to this organization's paid or bonus slots. example: limit: 3 used: 2 paid: limit: 3 used: 2 bonus: limit: 1 used: 0 delegated_used: 0 team_members: type: object description: Team member cap. properties: limit: type: - integer - 'null' used: type: integer example: limit: 50 used: 4 pos_integration: type: boolean description: POS bridge connections for the organization's locations. analytics_export: type: boolean description: CSV / API analytics export. automations: type: boolean description: >- Whether automated push campaigns are enabled for this organization - the org's EFFECTIVE entitlement (plan defaults merged with any per-org overrides). Values follow current plan configuration. physical_gift_cards: type: boolean description: Physical pre-printed gift card batches. gift_card_online_sales: type: boolean description: Online gift card sales. customer_grace: type: - object - 'null' description: >- Present ONLY while a customer-cap grace window is engaged (soft-landing after downgrades). properties: grace_active: type: boolean grace_ends_at: type: integer description: Unix seconds when the grace window closes. BillingDetails: type: object description: >- Billing identity used on issued invoices. Slovak/Czech tax identifiers included where registered. properties: company_name: type: string description: Legal entity name as it appears on invoices. example: Demo Bakery s.r.o. tax_id: type: - string - 'null' description: Company registration number (IČO in SK/CZ). example: '12345678' vat_id: type: - string - 'null' description: Domestic tax id (DIČ). example: '1020304050' vat_id_intra_eu: type: - string - 'null' description: >- EU VAT id (IČ DPH) - present only for VAT-registered entities. Drives reverse-charge treatment on cross-border invoices. example: SK1020304050 address: $ref: '#/components/schemas/Address' email: type: string format: email description: Invoice delivery address. example: billing@demo-bakery.example phone: type: - string - 'null' description: E.164 contact phone. example: '+421900000000' Address: type: object description: >- Postal address block. `line1` and `city` always present; `country` is ISO 3166-1 alpha-2 uppercase. properties: line1: type: string example: Obchodná 12 description: Street address, one line (street + number). city: type: string example: Bratislava description: City. Always present. postal_code: type: string example: '81106' description: Postal code. country: type: string pattern: ^[A-Z]{2}$ example: SK description: ISO 3166-1 alpha-2, uppercase. required: [] 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.