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.<numeric>.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.).

GET /v1/organization

Retrieve your organization

cURL

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

200

{
  "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": "[e-mail]",
    "phone": "[phone]"
  },
  "email_preferences": {
    "onboarding": true,
    "feature_adoption": true,
    "achievements": true,
    "reports": true,
    "gift_card_sales": false
  },
  "created_at": 1757664000,
  "updated_at": 1782561600
}

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.

Response

200

application/json

Organization.

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).

id · string · required

Opaque id for support reference ONLY - never accepted as input anywhere.

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

Example:

"org_01HXYZORG001"

object · string · required

Always "organization".

Allowed value: "organization"

name · string · required

Display name.

Example:

"Demo Bakery s.r.o."

country · string · required

ISO 3166-1 alpha-2.

Pattern: ^[A-Z]{2}$

Example:

"SK"

default_currency · string · required

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.

Example:

"EUR"

default_language · enum<string> · required

Fallback language for passes + notifications.

Available options: sk, cs, en, de

Example:

"sk"

account_state · enum<string> · required

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

Available options: pending_activation, awaiting_claim, active, paused, cancelling, cancelled, locked

Example:

"active"

plan · object · required

Subscription snapshot. The tier/interval enum is closed - new intervals ship as documented additive changes.

Show child attributes

caps · object · required

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.

Show child attributes

created_at · integer · required

Unix seconds.

Example:

1757664000

billing_details · object

Billing identity used on issued invoices. Slovak/Czech tax identifiers included where registered.

Show child attributes

email_preferences · object

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.

Show child attributes

Example:

{
  "onboarding": true,
  "feature_adoption": true,
  "achievements": true,
  "reports": true,
  "gift_card_sales": true
}

updated_at · integer

Unix seconds of last change.

Example:

1782561600