Add-ons
The add-on catalog, the ones this workspace has ever held and the live usage of the metered ones — and the two self-serve writes to activate or cancel one.
Download the full API pública projection: openapi.json.
| Method | Path | What it does |
|---|---|---|
GET | /entitlements | List the add-on catalog, this workspace's entitlements, and live usage |
POST | /entitlements/{feature}/activate | Self-serve activate an add-on (returns needs_enrollment without a payment mandate) |
POST | /entitlements/{feature}/cancel | Cancel an add-on at period end |
GET /entitlements
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.
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": {},
"created_at": "2026-09-01T12:00:00.000Z",
"updated_at": "2026-09-01T12:00:00.000Z"
}
],
"usage": {
"tasador": {
"used": 3,
"free_allowance": 10,
"period": "2026-09"
}
}
}
}Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429
POST /entitlements/{feature}/activate
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. Idempotent on an already-active feature (re-answers the same active row rather than erroring).
| Parameter | In | Type | Required | Constraints |
|---|---|---|---|---|
feature | path | string | yes | mín. 1, máx. 64 |
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": {},
"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}/cancel
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.
| Parameter | In | Type | Required | Constraints |
|---|---|---|---|---|
feature | path | string | yes | mín. 1, máx. 64 |
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