Cómo crear una facturación basada en el uso con Stripe y Webflow

La facturación por uso parece una decisión de precios, pero se comporta como una de ingeniería. La factura a fin de mes es tan fiable como los eventos que registraste durante ese periodo, y no hay forma de reconstruir una solicitud que nunca mediste.

Lo que hace que esto sea más difícil de lo que debería ser en 2026 es que Stripe tiene ahora tres generaciones de facturación por uso en su documentación, y dos de ellas son el lugar equivocado para empezar un nuevo desarrollo.

Esta guía cubre cuál deberías elegir y luego construye el ciclo de medición y facturación en Webflow Cloud, donde tu aplicación ya convive con el sitio de marketing.

¿Sobre qué producto de facturación por uso de Stripe deberías construir?

Stripe redirige ahora las nuevas integraciones basadas en el uso hacia Metronome, mantiene la facturación básica por uso totalmente compatible para quienes ya la utilizan y marca el enfoque original de registros de uso como legado. Elegir la opción incorrecta significa tener que reconstruir la integración más adelante.

Stripe afirma que Metronome es la opción principal para todas las integraciones nuevas, donde Metronome se encarga de la medición, la valoración y la facturación, mientras que Stripe gestiona el cobro de pagos, los impuestos y el reconocimiento de ingresos.

Al mismo tiempo, aclara que si ya tienes una integración básica de facturación por uso, no necesitas migrar, ya que Stripe seguirá dándole soporte completo.

Para un desarrollo nuevo, la respuesta por defecto es Metronome; la opción básica es la excepción, no el punto de partida. La siguiente comparativa muestra lo que te cuesta cada elección, incluyendo la única categoría donde la opción básica sigue estando claramente por delante:

Stripe menciona que la opción básica "funciona mejor para empresas con modelos de precios de pago por uso", pero esa frase aparece bajo un encabezado dirigido a quienes ya tienen una integración con Billing Meters, por lo que no es un argumento para empezar por ahí.

Las dos últimas filas son el verdadero argumento a favor de la opción básica en un desarrollo nuevo. Stripe documenta brechas de interoperabilidad entre Metronome y varios de sus propios productos: Connect, Adaptive Pricing, Workflows y el Dashboard de Stripe no son compatibles, y Checkout solo funciona con llamadas a la API personalizadas y configuración de webhooks. Si tu producto depende de alguno de ellos, la opción básica es la elección lógica y el resto de esta guía te será útil.

El resto de esta guía desarrolla la ruta de facturación básica basada en el uso, ideal para dos tipos de lectores: aquellos que ya facturan a través de Billing Meters o quienes necesitan los productos de Stripe que Metronome aún no cubre. Si no es tu caso, detente aquí y empieza con Metronome.

¿Qué necesitas para configurar la facturación por uso con Stripe y Webflow?

Necesitas una cuenta de Stripe con un medidor y un precio basado en el uso, un proyecto de Webflow Cloud desde el cual registrar eventos y un lugar seguro donde guardar tu propia copia de lo que has contabilizado.

Aquí tienes la lista completa:

• Una cuenta de Stripe con un medidor de facturación y un precio vinculado a él

• Un proyecto de Webflow Cloud que ejecute una aplicación Next.js, con Next.js 15 o superior y Node.js 22 o posterior en local

• Una clave secreta de Stripe y un secreto de firma de webhook, almacenados como variables de entorno

• Un lugar donde registrar el uso por tu cuenta, como el binding de SQLite de Webflow Cloud, para que puedas conciliar los datos con Stripe más adelante

Webflow Cloud funciona en todos los planes de sitio, incluido el nivel gratuito Starter, aunque para vincular la aplicación a un dominio personalizado se requiere el plan Premium o superior. Una vez que tengas esto listo, todo depende de un hábito: nunca permitas que ocurra una acción facturable sin registrarla, y nunca la registres dos veces. Te explicamos cómo.

5 pasos para registrar el uso y facturarlo a través de Stripe

La estructura consiste en un medidor, un precio, una ruta que registra eventos, un webhook para los resultados de facturación y tu propio libro contable para comparar con Stripe.

El orden es importante aquí, ya que cada paso depende de una decisión tomada en el anterior.

1. Crea el medidor y decide qué significa una unidad

En el Dashboard de Stripe, crea un medidor de facturación y asígnale un nombre de evento. Ese nombre es la cadena que enviará tu código; coincide con el event_name del medidor y tiene un límite de 100 caracteres.

Esto es también casi irreversible: una vez que configuras un medidor, Stripe no te permitirá cambiar nada más allá del nombre visible. La parte más difícil de este paso no está en Stripe. Decide, por escrito, qué es una unidad facturable: una llamada a la API, mil tokens, un día de asiento o una hora de gigabyte.

Las facturas en disputa suelen deberse a que esta definición es imprecisa, porque un cliente que interpreta las "solicitudes" de forma distinta a ti no está equivocado; simplemente está leyendo una palabra ambigua.

Ten en cuenta también la agregación. Stripe ofrece tres fórmulas: Suma, Recuento y Último. Por lo tanto, un medidor que factura según el valor reportado más recientemente se comporta de forma distinta a uno que suma las solicitudes, y no existe una opción de pico o máximo para configurar.

Terminas este paso con un nombre de evento anotado y una definición de una sola frase de lo que es una unidad, que un agente de soporte podría leer en voz alta.

2. Vincula el medidor a un precio y a una suscripción

Crea un producto y un precio recurrente que haga referencia al medidor, luego suscribe a tu cliente. La suscripción hace que el uso sea facturable; un medidor por sí solo registra números que nunca llegan a una factura.

Aquí es también donde fijas el modelo de precios. Una tarifa plana por unidad es la opción más sencilla y los precios escalonados están disponibles, pero si quieres créditos que se consuman o un compromiso mínimo, detente y revisa la decisión de Metronome anterior en lugar de intentar aproximarla con cupones.

Guarda el ID de cliente de Stripe en un lugar al que puedas acceder desde la aplicación, porque cada evento de medidor que envíes debe identificar al cliente al que pertenece. Almacenarlo junto a tu propio registro de usuario al momento del registro te permite tenerlo siempre a mano.

Finaliza este paso con una suscripción activa cuya próxima factura muestre una línea de uso en cero.

3. Registra eventos de medidor desde un gestor de rutas

Tu servidor debe registrar el uso cuando ocurre el evento facturable, no en el navegador. Un cliente que pueda llamar a tu endpoint de facturación puede reportar menos de lo real.

El gestor es sencillo:

// app/api/usage/route.ts
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  maxNetworkRetries: 2,
})

export async function POST(request: NextRequest) {
  const { customerId, units, requestId } = (await request.json()) as {
    customerId: string
    units: number
    requestId: string
  }

  if (!customerId || !requestId) {
    return NextResponse.json({ error: 'Missing customer or request ID' }, { status: 400 })
  }

  await stripe.billing.meterEvents.create({
    event_name: 'api_request',
    payload: {
      // Both keys are the meter's defaults. If you renamed them on the
      // meter, these must match the meter, not the other way round.
      stripe_customer_id: customerId,
      // value is a string, even though it holds a number.
      value: String(units),
    },
    // Stripe enforces uniqueness on this within a rolling window of
    // at least 24 hours, so reuse it on a retry. Max 100 characters.
    identifier: requestId,
  })

  return NextResponse.json({ recorded: true })
}

Hay tres detalles que es fácil pasar por alto. Las claves de la carga útil son los valores predeterminados del medidor: stripe_customer_id y value, y si cambiaste el nombre de alguno en el medidor, la carga útil debe coincidir con el medidor y no al revés.

El valor se envía como una cadena aunque represente un número. Stripe aplica la unicidad en un identifier dentro de un período continuo de al menos 24 horas, por lo que un reintento dentro de ese margen que reutilice el identificador es seguro, mientras que uno que genere un nuevo identificador facturará dos veces.

Una entrega repetida que llegue días después cae fuera de ese margen, lo cual es un segundo argumento a favor de llevar un registro en el siguiente paso.

Dos límites determinan cómo realizar esto a gran escala. Stripe limita los eventos de medidor a 1000 por segundo por cuenta y, por separado, solo permite una llamada simultánea por cliente y medidor, por lo que una ráfaga de solicitudes paralelas para un mismo cliente colisionará. La respuesta habitual es pre-agregar antes de enviar.

Despliega esto y una llamada debería devolver { recorded: true }, y el evento aparecerá asociado al cliente en el Dashboard poco después, en lugar de al instante.

4. Lleva tu propio registro y reconcílialo con Stripe

Registra cada acción facturable tanto en tu propia base de datos como en Stripe. Puede parecer redundante durante la primera semana, pero luego será lo único que te permita responder a un cliente que pregunta por qué aumentó su factura.

Stripe procesa los eventos de medición de forma asíncrona, tal como indica claramente su documentación: el uso agregado en los resúmenes de eventos y en las próximas facturas podría no reflejar inmediatamente los eventos que acabas de enviar.

Esto tiene dos consecuencias que conviene tener en cuenta al diseñar. Un panel de uso que lea directamente de Stripe tendrá retraso, así que es mejor leerlo desde tu propio registro. Además, una tarea de reconciliación que compare tus conteos con los de Stripe debe permitir ese margen de tiempo en lugar de lanzar alertas ante cualquier diferencia.

El binding de SQLite de Webflow Cloud está lo suficientemente cerca de la aplicación como para que esto sea económico; basta con una tabla sencilla que incluya cliente, nombre del evento, cantidad, identificador y marca de tiempo. Usa el mismo identificador que enviaste a Stripe para que ambos lados puedan cruzarse.

Tras este paso, podrás generar, para cualquier cliente y periodo, la lista de eventos por los que crees haber cobrado.

5. Gestiona los resultados de facturación con un webhook verificado

La medición es solo la mitad del proceso. La otra mitad consiste en reaccionar cuando una factura falla, una suscripción caduca o el uso supera un umbral importante, y eso llega a través de un webhook.

La verificación en Webflow Cloud tiene un requisito específico que conviene conocer antes de depurarla:

// app/api/stripe-webhook/route.ts
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  maxNetworkRetries: 2,
})

export async function POST(request: NextRequest) {
  const signature = request.headers.get('stripe-signature')
  if (!signature) {
    return NextResponse.json({ error: 'Unsigned request' }, { status: 400 })
  }

  // Read the raw text. Parsing first changes the bytes and the
  // signature will never match.
  const body = await request.text()

  let event: Stripe.Event
  try {
    // Async form: the Workers build uses Web Crypto, which cannot
    // run synchronously.
    event = await stripe.webhooks.constructEventAsync(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET as string
    )
  } catch {
    return NextResponse.json({ error: 'Bad signature' }, { status: 400 })
  }

  if (event.type === 'invoice.payment_failed') {
    const invoice = event.data.object as Stripe.Invoice
    await flagAccountForDunning(invoice.customer as string)
  }

  return NextResponse.json({ received: true })
}

La versión de la biblioteca de Stripe para Workers selecciona un proveedor de Web Crypto, y ese proveedor solo realiza trabajo asíncrono, por lo que el método síncrono constructEvent arroja un error en lugar de verificar.

Usa constructEventAsync, que es lo que utiliza el ejemplo de Cloudflare Worker de Stripe. Lee también el cuerpo como texto sin formato, ya que el análisis y la re-serialización alteran los bytes que cubre la firma.

Una vez que esto esté activo, un pago fallido debería mover la cuenta al estado de cobro (dunning) que utilices, y deberías poder activarlo desde la CLI de Stripe en lugar de esperar a que una tarjeta real sea rechazada.

¿Qué causa que la facturación por uso de Stripe falle en Webflow Cloud?

Los problemas de facturación por uso suelen ser silenciosos, lo cual es precisamente lo que los hace costosos. No hay errores, el producto sigue funcionando y el primer síntoma es una factura que nadie puede explicarle al cliente que la recibe.

Hay cuatro fallos que aparecen repetidamente, y el primero es el que debes probar deliberadamente antes del lanzamiento.

El uso nunca aparece en la factura

Causa: El evento de medición se acepta pero no está conectado a nada facturable. Por lo general, la suscripción utiliza un precio que no hace referencia al medidor, o el nombre del evento en el código no coincide exactamente con el nombre del evento en el medidor, incluyendo mayúsculas y minúsculas.

Solución: Comprueba el nombre del evento carácter por carácter frente al medidor y, luego, confirma que la suscripción del cliente tenga un precio que haga referencia a ese medidor. Un evento de medición para un cliente válido sin una suscripción coincidente se acepta y se registra, por lo que una respuesta 200 no te dice nada sobre si se llegará a facturar.

Stripe informa de los otros casos de forma asíncrona en lugar de hacerlo en la API: suscríbete a v1.billing.meter.no_meter_found y v1.billing.meter.error_report_triggered, que detectan nombres de eventos que no coinciden, clientes desconocidos, valores faltantes o marcas de tiempo demasiado antiguas.

A los clientes se les cobra dos veces por la misma acción

Causa: Un reintento envió un segundo evento de medición con un nuevo identificador. Todo lo que puede ejecutarse dos veces terminará haciéndolo: una reentrega de cola, un reintento del cliente o un despliegue que vuelve a ejecutar un trabajo.identifier

Solución: Deriva el identificador del elemento que se está facturando en lugar de generarlo al momento del envío, de modo que la misma acción siempre produzca el mismo identificador. Si ya tienes un ID de solicitud o de trabajo, úsalo.

Un envío duplicado dentro de la ventana de unicidad de Stripe se rechaza en lugar de cobrarse, y tu propio registro muestra dos intentos con un mismo identificador, lo cual es precisamente lo que te indica que el reintento ocurrió.

Los identificadores generados aleatoriamente son el origen del fallo precisamente porque parecen correctos durante las pruebas: una ejecución manual nunca se repite, por lo que el error solo aparece bajo las condiciones de reintento en producción.

Detectarlo a tiempo es fundamental, ya que Stripe solo permite cancelar un evento de medición dentro de las 24 horas posteriores a su envío, y cancelar un uso que ya se ha incluido en una factura finalizada no corrige dicha factura.

El panel de uso no coincide con Stripe

Causa: Leer el uso actual desde Stripe esperando que sea inmediato. Stripe agrega los eventos de medición de forma asíncrona, por lo que un resumen leído momentos después del envío legítimamente estará desfasado.

Solución: Lee la cifra que ve el cliente desde tu propio registro, que es la fuente de verdad de lo que has contabilizado, y trata a Stripe como la fuente de verdad de lo que se cobra. Concilia ambos según un calendario con un margen de tolerancia en lugar de compararlos en tiempo real, y alerta solo cuando la diferencia persista tras el retraso.

La distinción es importante cuando un cliente disputa un cargo: necesitas poder decir qué contabilizaste y cuándo lo enviaste, independientemente de lo que Stripe haya terminado de agregar. Un panel conectado directamente a Stripe no puede responder a esa pregunta y, además, mostrará a los clientes un número que cambia por razones que ellos no pueden ver.

La compilación falla después de añadir las rutas de facturación

Causa: Una directiva runtime en uno de los nuevos archivos de ruta. Webflow Cloud despliega Next.js a través del adaptador OpenNext Cloudflare, el cual no es compatible con el entorno de ejecución edge de Next.js.export const runtime = 'edge'

Solución: Elimina la línea y vuelve a desplegar, ya que los Route Handlers ya se ejecutan en el entorno de Workers sin ella. Busca en todo el proyecto en lugar de solo en el archivo que editaste por última vez, porque una directiva perdida en cualquier lugar hace que falle toda la compilación.

Comprueba esto primero, ya que la propia página de Webflow para traer tu propia aplicación sigue indicando a los lectores de Next.js que añadan la directiva, por lo que la instrucción que seguiste podría ser la que está rompiendo la compilación. Los proyectos de facturación se topan con esto a menudo, ya que las rutas de pago se copian frecuentemente de ejemplos escritos para otras plataformas de alojamiento donde la directiva es necesaria o inofensiva.

Lo que puede construir a continuación con Stripe y Webflow

Una vez que el uso está medido y conciliado, lo interesante es lo que haces con esa cifra antes de que llegue la factura: alertas de uso al alcanzar un umbral, un límite flexible que degrada el servicio en lugar de cortarlo, o un medidor en la aplicación que muestra a los clientes su situación actual.

Si tu producto también vende compras únicas junto con la suscripción, nuestra guía de productos digitales de Stripe cubre ese flujo, y la guía de autenticación y pagos cubre la capa de cuenta subyacente a ambos. Para rutas de conexión sin código, consulta la integración de Webflow y Stripe.

Para una personalización más profunda más allá de lo que cubren esas guías, la documentación para desarrolladores de Webflow detalla las opciones de Route Handler, almacenamiento y entorno disponibles en Webflow Cloud.