Cupones

Crea códigos de descuento que los clientes pueden aplicar al momento de pagar. De porcentaje o monto fijo, con límite de tiempo o de usos, de un solo uso o recurrentes.

Los cupones se administran en el panel Commerce panel > Products > Coupons del builder, o a través del SDK en proyecta.commerce.coupons.

Anatomía de un cupón

Campo	Notas
code	El código promocional que los clientes escriben al pagar (p. ej. LAUNCH20)
percent_off o amount_off	Son mutuamente exclusivos. El porcentaje va de 1 a 100. El monto se expresa en la unidad monetaria más pequeña (centavos).
currency	Requerido para descuentos de tipo amount_off (código ISO de tres letras). Se acepta al momento de la creación y se reenvía a Stripe, pero no se almacena ni se devuelve por la API después.
duration	once (solo el primer pago), repeating (por duration_in_months), o forever
duration_in_months	Requerido cuando duration es repeating
max_redemptions	Límite total de usos entre todos los clientes
redeem_by	Fecha de vencimiento tras la cual el cupón deja de funcionar
name	Nombre visible que se muestra a los clientes
active	Interruptor para habilitar/deshabilitar sin eliminar

Crear un cupón

Desde la pestaña Coupons, haz clic en Add coupon y completa los campos. O mediante el SDK:

// 20% off forever
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 off, single use, expires in 30 days
await proyecta.commerce.coupons.create({
    code: 'WELCOME10',
    amount_off: 1000,
    currency: 'USD',
    duration: 'once',
    max_redemptions: 1,
    redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 50% off for the first 3 months of a subscription
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

Aplicar un cupón al momento de pagar

Los clientes pueden ingresar el código del cupón directamente en la página de checkout hospedada por Stripe — el campo de código promocional se muestra de forma automática.

await proyecta.commerce.checkout({
    customer_id,
    line_items: [{ variant_id: 'var_pro_monthly' }],
    success_url: 'https://myapp.com/welcome',
});

Pasar un código de cupón de forma programática en la llamada al checkout aún no está soportado.

Listar, actualizar, desactivar

// Browse every coupon (only lists coupons created via the SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// Paginate using data.has_more and the starting_after query parameter if needed.

// Disable a coupon (without deleting)
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

Nota: coupons.list() solo devuelve los cupones creados a través del SDK. Los cupones creados desde el Dashboard del builder no son visibles mediante coupons.list().

Notas y límites

• Los códigos y los montos de descuento son inmutables. Puedes actualizar el name visible y alternar active, pero no percent_off, amount_off ni el code en sí. Crea un nuevo cupón si necesitas condiciones distintas.
• times_redeemed se incrementa automáticamente y es de solo lectura — útil para rastrear el rendimiento de campañas.
• Los cupones se aplican por cliente, no por orden — si un cupón es forever y un cliente se suscribe, cada renovación obtiene el descuento.