Add-ons

Download the full API pública projection: openapi.json.

GET /entitlementsCopy Anchor Link

List the add-on catalog, this workspace's entitlements, and live usage

The Complementos hub read. catalog is the typed feature catalog (prices are PR-reviewed code, never a runtime SKU table); entitlements is one row per add-on this workspace has ever held; usage carries the live meter for each metered add-on over the current Santiago month — usage.tasador is \{ used, free_allowance, period \}, where used is aggregated on read from usage_event (never a counter) and free_allowance reflects any per-workspace override, so it is the same pair of numbers the access gate decides on. Each entitlement carries billed_by: vitrina when Vitrina invoices the add-on, any other value when another party covers it (Vitrina charges nothing, so a client shows it as included rather than at the catalog price). A row may also carry a time-boxed waiver: waiver_until is the last free calendar day (America/Santiago) and waiver_active says whether it covers the add-on right now; once it lapses the add-on bills normally with no further action. complimentary and covered_by say when the add-on carries no price on the invoice at all (granted free, or covered by the workspace's fixed contract / not-billed contract): a client then shows it as included and never the catalog price. offers says, per add-on, whether THIS workspace can buy it (available) and if not why (sandbox: a demonstration workspace; vertical: not sold to this type of business) — the same rule the activate route enforces with a 409 ADDON_NOT_OFFERED. activators names the active owners and admins a member without tenant:write can ask to activate one.

curl https://api.vitrinadev.com/api/v1/entitlements \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "catalog": [
      {
        "key": "vitrina_ads",
        "access": "entitlement",
        "flatClpMonth": 99000
      },
      {
        "key": "tasador",
        "access": "quota",
        "flatUfMonth": 0.5,
        "freeAllowance": 10,
        "meter": "tasador_valuation"
      }
    ],
    "entitlements": [
      {
        "tenant_id": "11111111-1111-4111-8111-111111111111",
        "feature": "vitrina_ads",
        "status": "active",
        "source": "self_serve",
        "granted_at": "2026-09-01T12:00:00.000Z",
        "cancel_at_period_end": false,
        "canceled_at": null,
        "metadata": {},
        "waiver_until": "2026-10-31",
        "created_at": "2026-09-01T12:00:00.000Z",
        "updated_at": "2026-09-01T12:00:00.000Z",
        "billed_by": "vitrina",
        "waiver_active": true,
        "complimentary": false,
        "covered_by": null
      }
    ],
    "usage": {
      "tasador": {
        "used": 3,
        "free_allowance": 10,
        "period": "2026-09"
      }
    },
    "offers": {
      "vitrina_ads": {
        "available": true,
        "reason": null
      },
      "tasador": {
        "available": true,
        "reason": null
      }
    },
    "activators": [
      {
        "user_id": "22222222-2222-4222-8222-222222222222",
        "name": "Ana Rojas"
      }
    ]
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /entitlements/{feature}/activateCopy Anchor Link

Self-serve activate an add-on (returns needs_enrollment without a payment mandate)

Grants feature to the workspace once an active payment mandate exists (\{ status: "active", entitlement \}); with none, answers \{ status: "needs_enrollment" \} and grants nothing — the caller routes the dealer through the Fintoc/Mercado Pago enrollment step and retries. No payment method is needed when the add-on costs the workspace nothing: its row is covered by another biller (billed_by other than vitrina) or sits inside an active waiver_until waiver; such an activation answers active and accrues no charge for the covered days. An add-on this workspace cannot buy answers 409 ADDON_NOT_OFFERED (details.reason: sandbox or vertical, the same answer GET /entitlements publishes in offers); reactivating an add-on the workspace still holds is never refused for that. Idempotent on an already-active feature (re-answers the same active row rather than erroring).

curl -X POST https://api.vitrinadev.com/api/v1/entitlements/<id>/activate \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "status": "active",
    "entitlement": {
      "tenant_id": "11111111-1111-4111-8111-111111111111",
      "feature": "vitrina_ads",
      "status": "active",
      "source": "self_serve",
      "granted_at": "2026-09-23T15:00:00.000Z",
      "cancel_at_period_end": false,
      "canceled_at": null,
      "metadata": {},
      "waiver_until": null,
      "created_at": "2026-09-23T15:00:00.000Z",
      "updated_at": "2026-09-23T15:00:00.000Z"
    }
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /entitlements/{feature}/cancelCopy Anchor Link

Cancel an add-on at period end

Flags the workspace’s feature row cancel_at_period_end: true — the add-on stays active through the period already paid for and turns off at rollover, never immediately. 404 when the workspace holds no entitlement for feature to cancel.

curl -X POST https://api.vitrinadev.com/api/v1/entitlements/<id>/cancel \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "status": "canceling",
    "entitlement": {
      "tenant_id": "11111111-1111-4111-8111-111111111111",
      "feature": "vitrina_ads",
      "status": "active",
      "source": "self_serve",
      "granted_at": "2026-09-01T12:00:00.000Z",
      "cancel_at_period_end": true,
      "canceled_at": "2026-09-23T15:00:00.000Z",
      "metadata": {},
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-23T15:00:00.000Z"
    }
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429