Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ProyectoFerretek/FerreMarket/llms.txt

Use this file to discover all available pages before exploring further.

The Promotions module (/promociones) lets you create and manage discount codes for FerreMarket customers. Each promotion is identified by a human-readable code, carries date-range validity, supports both percentage and fixed-amount discount types, and can be targeted to specific products, categories, or customer types. The module also includes a per-promotion analytics panel showing conversion rate, revenue generated, peak-usage hours, and top-selling products under the promotion.

​
Summary Statistics

Three KPI cards appear at the top of the Promotions page and update whenever the promociones array changes:
CardMetric
Promociones activasCount of promotions where estado === 'activo'
Total de usosSum of usosActuales across all promotions
Ingresos generadosSum of ingresoGenerado across all promotions, formatted as CLP

​
Promotion Fields

The Promocion TypeScript interface from src/types/index.ts defines all available fields:

​
Core fields

FieldTypeDescription
idstringUnique identifier assigned by Supabase
codigostringThe promo code entered at checkout (e.g. DESCUENTO20)
nombrestringHuman-readable name displayed in the admin UI
tipostringDiscount calculation method — 'porcentaje' or 'monto_fijo'
valornumberDiscount magnitude — percentage points or CLP amount depending on tipo
valorMaximonumber (optional)Maximum CLP discount cap for percentage promotions
montoMinimonumberMinimum purchase amount (CLP) required to apply the promotion
fechaIniciostringISO 8601 start datetime in America/Santiago timezone
fechaFinstringISO 8601 expiry datetime in America/Santiago timezone
estadostring'activo' / 'pausado' / 'expirado' / 'borrador'
combinablebooleanWhether the code can be stacked with other active promotions
descripcionstring (optional)Longer description shown in communications
fechaCreacionstringISO 8601 timestamp when the promotion was created
creadoPorstringUsername or 'Admin'

​
Usage limits

FieldTypeDescription
limiteTotalUsosnumber (optional)Maximum times the code can be redeemed across all customers
limiteUsosPorClientenumber (optional)Maximum redemptions per individual customer
usosActualesnumberRunning count of times the code has been used

​
Targeting fields

FieldTypeDescription
aplicaAstringScope: 'toda_tienda', 'productos', or 'categorias'
productosIncluidosstring[]Product IDs the discount applies to (when aplicaA === 'productos')
productosExcluidosstring[]Product IDs explicitly excluded from the discount
categoriasIncluidasstring[]Category IDs the discount applies to (when aplicaA === 'categorias')
categoriasExcluidasstring[]Category IDs explicitly excluded
tipoClientestringTarget audience: 'todos', 'nuevo', 'recurrente', etc.

​
Analytics fields

FieldTypeDescription
ingresoGeneradonumberTotal CLP revenue attributed to this promotion
valorPromedioCompranumberMean order value (CLP) for transactions using this code
tasaConversionnumberConversion rate as a percentage
horariosUsostring[]Usage data bucketed by hour band. The analytics modal iterates this with Object.entries(), treating it as a Record<string, number> keyed by bands such as '00-06', '06-12', '12-18', '18-24'.
productosVendidosstring[]Products sold under this promotion with quantity and revenue data

​
Creating a Promotion

1

Open the modal

Click the orange Nueva Promoción button in the top-right header. PromocionModal opens with all fields empty.
2

Set the code and name

Enter a unique codigo (e.g. FERREVERANO25) and a descriptive nombre. The code is case-sensitive and must be unique in the promociones table.
3

Choose type and value

Select Porcentaje or Monto Fijo. Enter the discount valor. For percentage discounts, optionally set a valorMaximo cap to prevent excessively large discounts on high-value orders.
4

Set date range and minimum purchase

Enter fechaInicio and fechaFin using the date-time pickers. Optionally set montoMinimo to require a qualifying cart value.
5

Configure usage limits

Set limiteTotalUsos (total redemptions across all customers) and limiteUsosPorCliente (per-customer cap). Leave at 0 for unlimited.
6

Set targeting rules

Choose the aplicaA scope and optionally populate include/exclude lists for products and categories.
7

Save

On save, agregarPromocion(promocionData) maps camelCase fields to the Supabase snake_case column schema and inserts the row. A success toast confirms the operation.

​
Promotion Types

​
Percentage (porcentaje)

Discounts the cart by valor percent of the qualifying subtotal: 
discount = subtotal × (valor / 100)
if valorMaximo > 0: discount = min(discount, valorMaximo)
final = subtotal − discount
Example: A valor: 20 promotion with valorMaximo: 50000 gives 20% off up to a maximum of CLP 50,000, regardless of cart size.

​
Fixed Amount (monto_fijo)

Deducts a flat CLP amount from the qualifying subtotal: 
discount = valor
final = max(subtotal − valor, 0)
Example: A valor: 15000 welcome promotion deducts CLP 15,000 from the cart when montoMinimo is met.

​
Targeting Rules

aplicaA valueBehaviour
toda_tiendaApplies to all products in the cart
productosApplies only to products whose IDs appear in productosIncluidos
categoriasApplies only to products belonging to categories in categoriasIncluidas
Items in productosExcluidos or categoriasExcluidas are always exempt, even when the scope is toda_tienda. The tipoCliente field further restricts which customers can redeem the code ('todos' means no restriction).

​
Usage Limits

Each promotion tracks its redemption count in usosActuales. The progress bar on each promotion card visualises this as (usosActuales / limiteTotalUsos) × 100. When a promotion reaches its limit, it transitions to expirado status automatically.
  • limiteTotalUsos — hard cap across the entire store. Useful for scarcity-based campaigns (“first 1,000 uses”).
  • limiteUsosPorCliente — prevents the same customer from stacking repeated redemptions. Set to 1 for single-use codes like new-customer welcome discounts.
Set combinable: false on high-value promotions to prevent customers from stacking multiple discount codes in a single transaction. When combinable is false, the checkout process must reject any attempt to apply a second code if one non-combinable promotion is already active in the cart.

​
Analytics

Click the Análisis button on any promotion card to open ModalAnalisis. The panel shows:

Revenue metrics

Total usos, ingresos generados (CLP), and valor promedio de compra — shown as three coloured KPI boxes.

Peak-hour chart

Horizontal bar chart of horariosUso bucketed by 6-hour bands (00-06, 06-12, 12-18, 18-24) showing relative activity volume.

Top products

Ranked list of productosVendidos showing product name, units sold, and revenue, with a proportional progress bar.

Detailed info

Full metadata grid: creation date, author, validity period, limiteUsosPorCliente, combinable flag, and tipoCliente scope.
The analytics modal also provides Exportar CSV and Exportar Excel buttons for downloading the promotion’s data for external reporting.

Build docs developers (and LLMs) love

Get started for freeTalk to us