Facturación por uso

Facturación por uso

Con la facturación por uso (metered billing) cobras a tus clientes según lo que consumen — solicitudes de API, gigabytes, transacciones procesadas — en lugar de (o además de) un precio fijo. El modelo se arma con cuatro piezas:

1. Medidor (meter): define QUÉ se mide y cómo se agrega (sum, count o last).
2. Plan por uso (metered plan): define CUÁNTO cuesta cada unidad medida.
3. Suscripción: conecta un cliente al plan; a partir de ahí, envías eventos de uso.
4. Factura: al cierre de cada período, el consumo agregado se factura automáticamente (en arrears — se cobra el período que terminó, no el que empieza).

1. Crea un medidor

curl -X POST "https://api.venflow.app/v1/usage/meters" \
  -H "Api-Key: pvk_live_abc123..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Solicitudes API",
    "event_name": "api_request",
    "aggregation_method": "sum",
    "unit_label": "solicitudes"
  }'

• event_name es el identificador que enviarás en cada evento de uso. Debe ser único en tu organización.
• aggregation_method define cómo se calcula el total del período:
  • sum — suma los valores de todos los eventos (ej. GB transferidos).
  • count — cuenta los eventos, ignorando sus valores (ej. llamadas realizadas).
  • last — toma el valor del último evento del período (ej. asientos activos).

2. Crea un plan por uso

curl -X POST "https://api.venflow.app/v1/plans" \
  -H "Api-Key: pvk_live_abc123..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests",
    "frequency": "monthly",
    "usage_type": "metered",
    "meter_id": "<meter_id>",
    "usage_pricing_model": "per_unit",
    "usage_unit_amount": 0.002
  }'

Reglas clave:

• Un plan metered no lleva price — el monto sale del consumo.
• usage_pricing_model puede ser:
  • per_unit — cada unidad cuesta usage_unit_amount (USD, admite micro-precios como 0.0005).
  • tiered — tramos graduados: cada tramo cobra su tarifa marginal (100 unidades a $0.50 + el resto a $0.30).
  • volume — tramos por volumen: TODAS las unidades cobran la tarifa del tramo que alcanzó el total.
• Con tiered/volume, usage_tiers es una lista de { up_to, unit_amount } y el último tramo debe ser abierto: "up_to": null.
• usage_type y meter_id son inmutables una vez creado el plan.
• ¿Fee fijo + por consumo? Un plan es flat o metered, nunca ambos: crea un plan flat y refiérele el plan metered como plan item — al hacer checkout, ambos quedan en la misma suscripción y se facturan en un solo documento.

3. Suscribe al cliente (checkout)

curl -X POST "https://api.venflow.app/v1/checkout/sessions" \
  -H "Api-Key: pvk_live_abc123..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{ "plan": "<plan_id>" }'

Para un plan metered la sesión muestra amount_total: 0: no se cobra nada en el checkout. El cliente registra su método de pago, la suscripción se activa sin factura inicial y la primera factura llega al cierre del período con el consumo acumulado.

4. Envía eventos de uso

curl -X POST "https://api.venflow.app/v1/usage/events" \
  -H "Api-Key: pvk_live_abc123..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_request",
    "customer_id": "<customer_id>",
    "subscription_id": "<subscription_id>",
    "value": 100,
    "timestamp": "2026-07-20T12:00:00Z",
    "idempotency_key": "req_2026_07_20_0001"
  }'

• La ingesta es asíncrona e idempotente: si reintentas con el mismo idempotency_key, el evento duplicado se ignora sin error. Usa una clave determinística por evento (ej. el ID de tu registro interno).
• Solo se aceptan eventos de suscripciones activas (también en trial o en proceso de cancelación). La suscripción debe tener un item con un plan metered del medidor correspondiente; si no, la API responde con error.

5. Consulta el consumo del período

curl "https://api.venflow.app/v1/subscriptions/<subscription_id>/usage" \
  -H "Api-Key: pvk_live_abc123..." \
  -H "Organization: org_xyz789..."

Devuelve el consumo del período actual por medidor: total_usage (eventos pendientes de agregar) y unbilled_amount (monto ya agregado, pendiente de facturar). El historial de eventos está en GET /v1/subscriptions/<id>/usage/events.

Cómo se factura

• Al cierre de cada período, el consumo agregado entra como líneas de la factura del ciclo, con IVA calculado igual que las líneas fijas. Los descuentos de la suscripción no aplican a las líneas de uso.
• Si el período cierra con consumo cero en una suscripción 100 % por uso, no se genera factura — el período simplemente avanza.
• Trial: el consumo durante el período de prueba es gratis (se descarta al terminar el trial).
• Cuotas (billing_cycles): la última factura incluye el consumo del último período antes de cancelar automáticamente la suscripción.
• Cancelación a fin de período: la factura final incluye el consumo del último período antes de que la suscripción pase a cancelled.
• Los resultados fluyen por los webhooks existentes (invoice.*, payment.*) — no hay tipos de evento nuevos.