> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestión de suscripciones

> Elija un plan, suscríbase a través del pago, administre complementos y gestione la cancelación utilizando la API o la consola.

Puede gestionar todo su ciclo de vida de facturación a través de la API o la consola. Esta guía cubre cómo listar planes, estimar costos, crear una sesión de pago, verificar su suscripción, adjuntar complementos y cancelar cuando sea necesario.

## Requisitos previos

* Una cuenta de Truthlocks con un inquilino activo.
* Una clave API con permisos de facturación. Consulte [Claves API](https://docs.truthlocks.com/es/api-reference/api-keys/create.md) para crear una.

## Elegir un plan

Truthlocks ofrece cinco niveles de planes. Utilice el endpoint de planes para obtener el catálogo completo; este es un endpoint público y no requiere autenticación.

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/plans
```

```json theme={null}
[
  {
    "key": "plan_developer",
    "name": "Developer",
    "price": 0,
    "currency": "USD",
    "interval": "month",
    "features": ["500 mints/month", "Plan-dependent verifications", "Community support"],
    "highlight": false
  },
  {
    "key": "plan_starter",
    "name": "Starter",
    "price": 29,
    "currency": "USD",
    "interval": "month",
    "features": ["Higher quotas", "3 webhook endpoints", "Priority processing"],
    "highlight": true
  }
]
```

Consulte [descripción general de facturación](https://docs.truthlocks.com/es/billing/overview.md#plan-tiers) para una comparación de todos los planes.

## Estimar sus costos

Antes de suscribirse, use el endpoint de estimación para obtener una recomendación de plan basada en su uso esperado. Este también es un endpoint público.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "expected_verifications_monthly": 10000,
    "team_seats": 5,
    "webhook_endpoints_needed": 5,
    "storage_gb": 10
  }'
```

La respuesta incluye un plan recomendado y un total mensual estimado. Para un desglose de costos por partida, utilice el punto final [factura proyectada](https://docs.truthlocks.com/es/api-reference/billing/projected-invoice.md) en su lugar.

## Consultar sus tarifas actuales

Las tarifas efectivas por uso de su inquilino dependen de su lista de precios y región. Obténgalas con:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/rates \
  -H "X-API-Key: tl_live_..."
```

La respuesta incluye tarifas base y cualquier ajuste de precios regional:

```json theme={null}
{
  "rate_card": { "id": "rc_default", "name": "Standard Rates", "currency": "USD" },
  "items": [
    { "metric": "attestations.mint", "unit_price": 25, "volume_min": 0, "volume_max": 0 },
    { "metric": "verifications", "unit_price": 10, "volume_min": 0, "volume_max": 0 }
  ],
  "is_default": true,
  "regional_rates": {
    "region": "TIER_1",
    "multiplier": 1.0,
    "mint_rate_cents": 25,
    "verify_rate_cents": 10
  }
}
```

> [!NOTE]
>
> Si su organización tiene una tarjeta de tarifas personalizada asignada por un administrador de plataforma, esas tarifas aparecerán aquí en lugar de las predeterminadas.

## Suscribirse a un plan

Cree una sesión de pago para iniciar o actualizar su suscripción. El servicio de facturación selecciona automáticamente el proveedor de pago correcto para su región.

**1. Crear una sesión de pago**

Llame al endpoint de pago con el plan que desea y las URL de redireccionamiento:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/checkout \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_key": "STARTER",
    "success_url": "https://yourapp.com/billing?success=true",
    "cancel_url": "https://yourapp.com/billing?canceled=true"
  }'
```

La respuesta contiene una `checkout_url` alojada por el proveedor de pagos.

**2. Redirigir a la caja**

Envíe al usuario a `checkout_url` para completar el pago.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/billing/checkout", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_key: "STARTER",
    success_url: `${window.location.origin}/billing?success=true`,
    cancel_url: `${window.location.origin}/billing?canceled=true`,
  }),
});
const { checkout_url } = await res.json();
window.location.href = checkout_url;
```

**3. Confirmar la suscripción**

Después del pago, verifique que la suscripción esté activa:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/subscription \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": false
}
```

> [!TIP]
>
> Opcionalmente, puede pasar un parámetro `provider` (`stripe`, `paystack` o `flutterwave`) para anular el enrutamiento automático basado en la región. Consulte [enrutamiento del proveedor](https://docs.truthlocks.com/es/billing/provider-routing.md) para obtener más detalles.

## Adjuntar complementos

Los complementos amplían su plan con capacidades adicionales. Adjúntelos a través de la API:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "addon_key": "addon_seat",
    "quantity": 2
  }'
```

Si el complemento tiene un precio, la respuesta incluye un `checkout_url` para completar el pago. Los complementos gratuitos se activan inmediatamente.

> [!NOTE]
>
> Los precios de los complementos se ajustan automáticamente según el país de facturación de su organización. Los inquilinos en regiones de menor costo pagan una tarifa reducida; por ejemplo, el Paquete de Cumplimiento cuesta $149.50/mes en Nigeria (multiplicador de 0.5x) en lugar del precio base de $299. Consulte [precios regionales de complementos](https://docs.truthlocks.com/es/billing/overview.md#regional-add-on-pricing) para ver la tabla de niveles completa.

Para eliminar un complemento:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"addon_key": "addon_seat"}'
```

Consulte [administrar complementos](https://docs.truthlocks.com/es/api-reference/billing/addons.md) para obtener el catálogo completo de complementos y los detalles de la respuesta.

## Monitorear el uso

Rastree el consumo de su ciclo de facturación actual para mantenerse dentro de los límites de su plan:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

Para verificar si una operación específica está dentro de la cuota antes de realizarla:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/limits/check \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metric": "attestations.mint", "amount": 1}'
```

## Abrir el portal de facturación

Redirija a los usuarios al portal de autoservicio de su proveedor de pagos para actualizar los métodos de pago, ver facturas o administrar su suscripción:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/portal \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.com/settings/billing"
  }'
```

La respuesta incluye un `portal_url`. Redirija al usuario a esa URL. Las sesiones del portal caducan rápidamente, así que genere una URL nueva cada vez.

## Cancelar una suscripción

Para cancelar, llame al endpoint de cancelación. La cancelación se hará efectiva al final del período de facturación actual; mantendrá acceso completo hasta entonces.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/cancel \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": true
}
```

Una vez finalizado el período, su cuenta se degrada al plan Desarrollador (gratuito). Para volver a suscribirse, cree una nueva [sesión de pago](https://docs.truthlocks.com/es/api-reference/billing/checkout.md).

> [!WARNING]
>
> No puede deshacer una cancelación a través de la API. Para reanudar su suscripción, debe volver a pasar por el proceso de pago.

## Relacionado

> [card] [Resumen de facturación](https://docs.truthlocks.com/billing/overview.md)
>
> Planifica niveles, tarifas, derechos y complementos.

> [card] [Enrutamiento del proveedor](https://docs.truthlocks.com/billing/provider-routing.md)
>
> Cómo se enrutan los pagos por región.

> [card] [Referencia de la API de facturación](https://docs.truthlocks.com/api-reference/billing/config.md)
>
> Referencia completa del endpoint de la API de facturación.

> [card] [Derechos](https://docs.truthlocks.com/api-reference/billing/entitlements.md)
>
> Verifique sus funciones y cuotas activas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.