# Perkss | Documentation

## Instructions for AI Agents

- For clean Markdown of any page, append `.md` to the page URL
- For section-specific indexes, append `/llms.txt` to any section URL
- For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.perkss.io/_mcp/server

## Docs

- [¿Qué es Perkss?](https://docs.perkss.io/home/empieza-aqui/que-es-perkss.md): Perkss es una plataforma de fidelización que conecta tu tienda física y tu tienda Shopify sobre un mismo backend, para que puedas premiar a tus clientes por comprar contigo. En tienda física montas un programa de cashback o de sellos; en Shopify, uno de puntos o cashback.
- [Cómo se adapta Perkss a cada superficie](https://docs.perkss.io/home/empieza-aqui/que-superficie-usas.md): En tienda física montas un programa de sellos o de cashback — lo que más se demanda en el mostrador. En Shopify, uno de puntos o de cashback. Eliges uno por superficie y Perkss se encarga del resto: tarjeta wallet, perfil del cliente y recompensas funcionan igual en ambas.
- [Monta tu programa de fidelización en 15 minutos](https://docs.perkss.io/home/empieza-aqui/monta-tu-programa-en-15-minutos.md): En 15 minutos dejas tu programa listo: configuras tu marca, eliges el tipo de programa (cashback o sellos), diseñas la tarjeta wallet que tus clientes guardarán en su móvil, creas tu web de registro y activas tu plan. Sin app que descargar para tus clientes y sin tocar nada técnico.
- [Checklist de onboarding: todo lo que tienes que hacer para lanzar](https://docs.perkss.io/home/empieza-aqui/checklist-de-onboarding.md): Esta es la lista completa de pasos para lanzar tu programa de fidelización, en el orden en que debes hacerlos. El orden cambia según tu superficie: en tienda física das de alta a tu equipo antes de probar el canje; en Shopify primero eliges plan y luego personalizas el tema.
- [Tipos de programa en Perkss](https://docs.perkss.io/home/conceptos/tipos-de-programa.md): Perkss tiene tres tipos de programa: sellos, cashback y puntos. En tienda física eliges entre cashback o sellos; en Shopify, entre puntos o cashback. Niveles y referidos no son programas: son extensiones que se añaden encima del programa elegido.
- [¿Qué son los sellos en Perkss?](https://docs.perkss.io/home/conceptos/sellos.md): Los sellos son una tarjeta de fidelización tipo "punch card": el cliente acumula un sello por cada visita o compra hasta llegar a una meta que tú defines, y al completarla desbloquea una recompensa. Tú decides cuántos sellos hacen falta para completar la tarjeta y qué recompensa recibe el cliente.
- [¿Qué es el cashback en Perkss?](https://docs.perkss.io/home/conceptos/cashback.md): El cashback devuelve a tus clientes un porcentaje de cada compra como saldo real que pueden gastar en tu negocio — funciona como una tarjeta regalo que se recarga sola con cada visita. Tú eliges el porcentaje; Perkss calcula, acumula y muestra el saldo en el pase de Apple/Google Wallet del cliente a
- [¿Qué son los puntos en Perkss para Shopify?](https://docs.perkss.io/home/conceptos/puntos-shopify.md): Los puntos son una moneda de fidelización propia de tu tienda: el cliente los gana con reglas que tú configuras (por ejemplo, puntos por cada euro gastado) y los canjea después por recompensas de tu catálogo. Es uno de los dos modos de programa disponibles en Shopify -- el otro es cashback -- y elig
- [¿Qué son los niveles VIP en Perkss?](https://docs.perkss.io/home/conceptos/niveles.md): Los niveles VIP son tramos de cliente (por ejemplo "Gold", el nombre que aparece en la interfaz) que se desbloquean según el gasto u otro criterio que tú definas, y que dan beneficios cada vez mayores a quien sube de tramo. Cada nivel puede llevar un descuento automático permanente mientras el clien
- [¿Qué es el programa de referidos en Perkss?](https://docs.perkss.io/home/conceptos/referidos.md): El programa de referidos recompensa a tus clientes por invitar a sus amigos a comprar en tu tienda. Cuando un amigo invitado completa su primer pedido, tu cliente (el embajador) recibe una recompensa y el amigo también puede recibir la suya.
- [¿Cómo identifica Perkss a mis clientes?](https://docs.perkss.io/home/conceptos/clientes-e-identidad.md): En tienda física, el teléfono es la identidad única de cada cliente: dos altas con el mismo teléfono son el mismo cliente. En Shopify, la identidad se resuelve a través de la propia cuenta de cliente de tu tienda.
- [¿Qué es la tarjeta wallet de tus clientes?](https://docs.perkss.io/home/conceptos/tarjeta-y-wallet.md): La tarjeta wallet es el pase de Apple Wallet o Google Wallet que representa la membresía de cada cliente en tu programa. Muestra su saldo o progreso, sirve para identificarlo en el mostrador con un QR, y se actualiza solo cada vez que gana o canjea algo — sin que el cliente descargue ninguna app.
- [Instala Perkss en tu tienda Shopify y configura tu programa](https://docs.perkss.io/home/perkss-para-shopify/instalar-la-app-y-onboarding.md): Al abrir la app de Perkss por primera vez, un asistente te guía en 3 bloques: identidad de marca (nombre, logo y color), tipo de programa (puntos o cashback) y mecánica de ganancias. Al pulsar "Lanzar programa", tu programa de fidelización queda activo.
- [Elige el modo de tu programa: puntos o cashback](https://docs.perkss.io/home/perkss-para-shopify/elige-tu-modo-puntos-o-cashback.md): Tu tienda de Shopify funciona con puntos o con cashback, nunca los dos a la vez. Eliges el tipo de programa en el asistente inicial, y esa elección queda fijada al lanzar: cambiarla después requiere contactar con soporte.
- [Cómo activar el widget de fidelización en tu tema de Shopify](https://docs.perkss.io/home/perkss-para-shopify/widget-e-integracion-con-el-tema.md): El widget es un lanzador flotante que aparece en todas las páginas de tu tienda y abre un panel con el programa de fidelización: saldo, formas de ganar, recompensas y más. Se activa como cualquier app embed desde el editor de temas de Shopify.
- [Cómo aplicar tu marca (colores, tipografía y estilo) al widget y la página de fidelización](https://docs.perkss.io/home/perkss-para-shopify/brand-kit.md): Desde el Kit de marca configuras los colores, la tipografía, la forma y los iconos que se aplican a las superficies de tema de tu programa: el widget flotante, la página de fidelización y los bloques de producto y carrito. Puedes partir de un preset ya definido o ajustar cada elemento a mano, y prev
- [Cómo configurar los niveles VIP de tu programa en Shopify](https://docs.perkss.io/home/perkss-para-shopify/configurar-niveles.md): Configuras los niveles VIP desde Fidelización → Niveles VIP: creas cada nivel con su nombre, su posición en la escalera, el umbral de gasto para alcanzarlo y los beneficios asociados (una recompensa de entrada, perks automáticos y, si quieres, un multiplicador de earning para ese nivel). El cliente 
- [Cómo activar y configurar los referidos en tu tienda Shopify](https://docs.perkss.io/home/perkss-para-shopify/configurar-referidos.md): Activas el programa de referidos configurando dos recompensas separadas: una para el amigo invitado y otra para el embajador que invita. El amigo recibe siempre un código de descuento; el embajador recibe puntos, cashback o un premio del catálogo, según el modo de tu programa.
- [Cómo ofrecer un producto de tu catálogo como recompensa canjeable](https://docs.perkss.io/home/perkss-para-shopify/recompensas-por-producto.md): Puedes añadir un producto de tu catálogo como recompensa de tipo "Producto gratis": el cliente lo canjea con puntos o saldo y Shopify lo añade al carrito a coste 0 de forma automática, sin que tenga que pegar ningún código. Hoy, vincular el producto concreto a la recompensa se resuelve configurando 
- [Cómo mostrar recompensas de fidelización en el checkout de Shopify Plus](https://docs.perkss.io/home/perkss-para-shopify/recompensas-en-checkout-plus.md): Esta función solo está disponible si tu tienda tiene Shopify Plus, porque usa la extensibilidad de checkout (Checkout UI Extension) que Shopify reserva a ese plan — es la única funcionalidad de Perkss que sigue siendo exclusiva de Plus. Con ella, tus clientes ven y aplican su saldo o sus recompensas
- [Qué son la página de fidelización y el account hub que ve tu cliente](https://docs.perkss.io/home/perkss-para-shopify/pagina-de-fidelizacion-y-account-hub.md): Perkss crea dos superficies distintas para que tu cliente vea y gestione su fidelización en Shopify: la página de fidelización, una página pública de tu tienda indexable por buscadores, y el account hub, una extensión dentro de la cuenta de cliente nativa de Shopify. La primera sirve para atraer y e
- [Cómo mostrar los puntos que ganan tus clientes en la ficha de producto y el carrito](https://docs.perkss.io/home/perkss-para-shopify/puntos-en-pdp-y-carrito.md): Perkss puede mostrar en la ficha de producto y en el carrito cuántos puntos va a ganar el cliente si compra, calculados en tiempo real según el precio de la variante seleccionada. Se activa como bloque de tema desde el editor de temas de Shopify.
- [Cómo configurar tu cuenta y tu programa desde el CMS](https://docs.perkss.io/home/perkss-en-tienda-fisica/configura-tu-back-office-cms.md): El CMS es el panel web donde configuras todo tu programa de fidelización antes de lanzarlo: tu marca, tu programa de cashback o sellos, el formulario de alta, tus Locales y tus empleados. Todo vive bajo el menú Admin, accesible desde el menú lateral (Inicio, Miembros, Comunicaciones, Admin, Ajustes)
- [Cómo configurar tu programa de cashback en tienda física](https://docs.perkss.io/home/perkss-en-tienda-fisica/programa-de-cashback.md): Configuras tu programa de cashback desde el panel de administración en un solo formulario: eliges el porcentaje que ganan tus clientes en cada compra, decides si pueden canjear su saldo cuando quieran o solo a partir de un gasto mínimo, y opcionalmente les regalas un saldo de bienvenida al darse de 
- [Cómo configurar tu programa de sellos en tienda física](https://docs.perkss.io/home/perkss-en-tienda-fisica/programa-de-sellos.md): Configuras tu programa de sellos desde el Admin de tu panel: eliges el tipo "sellos" al crear el programa, defines cuántos sellos hacen falta para completar la tarjeta y qué recompensa recibe el miembro al conseguirlo. Una vez activo, el tipo de programa ya no se puede cambiar, así que conviene deci
- [Cómo personalizar la tarjeta wallet de tu tienda física](https://docs.perkss.io/home/perkss-en-tienda-fisica/personaliza-la-tarjeta-wallet.md): Desde Admin > Marca configuras el logo, los colores, el banner y la etiqueta de saldo del pase que tus clientes guardan en Apple Wallet o Google Wallet. Puedes previsualizar el resultado antes de publicarlo.
- [Cómo configurar el formulario de registro y compartir el enlace o QR](https://docs.perkss.io/home/perkss-en-tienda-fisica/formulario-de-registro.md): Cada empresa tiene un formulario público de alta en su propia URL (/register/tu-slug). Ahí pide nombre, apellido, email y teléfono a cualquier persona que quiera unirse a tu programa.
- [Cómo registrar una compra y aplicar un canje en el mostrador](https://docs.perkss.io/home/perkss-en-tienda-fisica/registrar-una-compra-y-aplicar-un-canje.md): Perkss no cobra la venta: tú cobras como siempre (efectivo, tarjeta, tu TPV). La app solo lleva la fidelización, y son dos gestos independientes: registrar la compra para que el cliente gane cashback o un sello, y aplicar un canje para que gaste su saldo o use una recompensa.
- [Cómo dar de alta a un cliente nuevo desde el mostrador](https://docs.perkss.io/home/perkss-en-tienda-fisica/alta-en-el-mostrador.md): No existe un botón para dar de alta a un cliente directamente desde tu app de empleado. El alta la completa el propio cliente en un formulario público (/register/{slug}) al que llega escaneando un QR o abriendo un enlace que tú le facilitas.
- [Cómo dar de alta a tus empleados y gestionar sus accesos](https://docs.perkss.io/home/perkss-en-tienda-fisica/empleados-cuentas-y-roles.md): Das de alta a cada empleado desde Admin > Empleados en tu CMS, con nombre y apellido. No necesitan usuario ni contraseña propios: el personal usa la app de empleado con la cuenta de tienda de su Local, y cada venta queda atribuida al empleado que elijas en ese momento.
- [¿Qué ve exactamente tu cliente en el programa de fidelización?](https://docs.perkss.io/home/perkss-en-tienda-fisica/lo-que-ve-tu-cliente.md): Tu cliente ve su programa de fidelización en tres sitios: el pase de su wallet (Apple o Google), su perfil web público, y el feed de actividad dentro de ese perfil. No existe una app de cliente que instalar — todo pasa por estos tres elementos, accesibles desde el móvil sin descargar nada más allá d
- [Cómo y cuándo se envían notificaciones push a la tarjeta wallet](https://docs.perkss.io/home/canales-y-mensajeria/notificaciones-push-del-wallet.md): Cada vez que cambia el saldo o los sellos de un cliente, su tarjeta wallet se actualiza sola y el móvil se lo notifica: en iPhone como una alerta en la pantalla de bloqueo, en Android como una notificación visible durante 7 días. No hace falta ninguna app propia de Perkss para el cliente — todo lleg
- [Cómo enviar emails a tus clientes desde Perkss](https://docs.perkss.io/home/canales-y-mensajeria/emails-a-tus-miembros.md): Hoy solo puedes enviar emails a tus clientes desde un dominio propio verificado — no existe un remitente de Perkss por defecto ni un envío de respaldo si no lo verificas. Antes de mandar tu primer email, tienes que conectar y verificar tu dominio (por ejemplo tutienda.com); hasta entonces, el envío 
- [Cómo verificar tu propio dominio de email](https://docs.perkss.io/home/canales-y-mensajeria/dominio-de-email-propio.md): Para enviar emails a tus clientes necesitas conectar y verificar tu propio dominio de envío. Perkss no tiene un remitente propio de respaldo: sin un dominio verificado, el envío de emails queda bloqueado.
- [¿Cómo personalizo mis emails con plantillas y variables?](https://docs.perkss.io/home/canales-y-mensajeria/plantillas-y-variables.md): Cuando escribes un email manual para tus miembros puedes insertar variables como {{customer_first_name}} o {{customer_balance}} y Perkss las sustituye por el dato real de cada destinatario al enviarlo. Escribes el email una vez, con las variables que necesites, y Perkss se encarga de rellenarlas per
- [Cómo importar tus clientes y sus saldos desde un CSV](https://docs.perkss.io/home/clientes-y-datos/importar-clientes-csv.md): Puedes traer tu lista de clientes y su saldo de cashback actual a Perkss subiendo un archivo CSV desde el panel. El sistema identifica a cada cliente por su teléfono, valida el archivo antes de tocar nada y solo después de tu confirmación crea los clientes y les asigna su saldo.
- [Cómo migrar tus clientes desde otra plataforma de fidelización](https://docs.perkss.io/home/clientes-y-datos/migrar-desde-otra-plataforma.md): Si vienes de otra plataforma de fidelización, puedes traer tus clientes a Perkss mediante una importación por fichero. El proceso general es: exportas los datos de tu plataforma anterior, los adaptas al formato que pide Perkss y los importas.
- [¿Caduca el saldo de cashback de mis clientes?](https://docs.perkss.io/home/clientes-y-datos/caducidad-y-estados-del-saldo.md): No, el saldo de cashback de tus clientes no caduca. Es un balance en euros que se queda acumulado en la cuenta del cliente hasta que lo canjea, sin fecha límite ni proceso automático que lo reduzca por el paso del tiempo.
- [Cómo borrar un cliente y atender una solicitud de baja de datos](https://docs.perkss.io/home/clientes-y-datos/borrar-un-cliente-gdpr.md): Cuando un cliente te pide que borres sus datos, lo haces desde la ficha del miembro en el CMS. Perkss anonimiza sus datos personales (nombre, apellido, email, teléfono y las notas internas que hayas guardado sobre él) pero conserva su ficha, su saldo y su historial de transacciones, para que la cont
- [Qué datos muestra el dashboard de tu CMS](https://docs.perkss.io/home/analitica/tu-dashboard-cms.md): Tu dashboard muestra 4 KPIs de tu programa, un gráfico principal y un top-5 de tus mejores miembros. Los KPIs y el gráfico cambian según si tu programa es de cashback o de sellos.
- [Qué KPIs debería vigilar en mi programa de fidelización](https://docs.perkss.io/home/analitica/kpis-que-medir.md): Tu dashboard del CMS te muestra 4 KPIs distintos según el tipo de programa que tengas activo (cashback o sellos), más un gráfico principal y un top-5 de miembros. No necesitas mirarlos todos a diario: con revisarlos una vez a la semana y una vez al mes tienes suficiente para saber si tu programa est
- [Cómo ver el rendimiento de tu programa de fidelización en Shopify](https://docs.perkss.io/home/analitica/analitica-en-shopify.md): Dentro del admin de la app, en Analíticas > Rendimiento del programa, tienes un panel completo con KPIs, tendencia de altas, distribución por nivel e ingresos atribuidos a tu programa. Filtras por rango de fechas y por nivel VIP, y puedes exportar la vista en CSV.
- [Cómo diseñar un buen programa de fidelización](https://docs.perkss.io/home/estrategia-y-playbooks/disena-un-buen-programa.md): Un buen programa de fidelización se diseña con tres decisiones: cuánto ofreces (% de cashback, número de sellos o reglas de puntos), qué ganas al dar de alta (bienvenida) y con qué frecuencia lo revisas. No hay un número mágico válido para todos los negocios: depende de tu margen y de tu frecuencia 
- [Lanza tu programa en 10 minutos](https://docs.perkss.io/home/estrategia-y-playbooks/lanza-tu-programa-en-10-minutos.md): Con el programa ya montado, lanzarlo son 10 minutos: pon el QR de registro en el mostrador, enseña a tu equipo los dos gestos (registrar compra y aplicar canje), haz una prueba real y anúncialo a tus clientes por push de wallet o email.
- [Cómo premiar la compra en tienda física](https://docs.perkss.io/home/estrategia-y-playbooks/premia-la-compra-en-tienda.md): Si quieres que tus clientes elijan pisar tu tienda en vez de comprar solo online, la palanca no es una feature nueva: es cómo usas lo que ya tienes. El QR de registro en mostrador, una bienvenida algo mejor en tienda y el pase wallet como recordatorio recurrente son las tres piezas que mueven la agu
- [Cómo invitar a tu equipo a la cuenta y elegir el idioma de tu CMS](https://docs.perkss.io/home/cuenta/tu-equipo-e-idiomas.md): Puedes invitar a otras personas a gestionar el CMS de Perkss por email, y elegir el idioma en el que se muestra el panel. Esto es distinto de dar de alta empleados de tienda: aquí hablamos de quién entra al CMS a configurar tu cuenta, no de tu equipo de mostrador.
- [Solución de problemas](https://docs.perkss.io/home/recursos/solucion-de-problemas.md): Este hub reúne los problemas más frecuentes que nos reportan los comercios, agrupados por tema, con un enlace directo a la página que explica la solución. La idea es que encuentres tu caso en unos segundos, sin tener que leer toda la documentación.
- [¿Qué ha cambiado recientemente en Perkss?](https://docs.perkss.io/home/recursos/novedades-changelog.md): El changelog de Perkss reúne las novedades del producto ordenadas por fecha. Según la gobernanza definida para esta documentación, cada entrada se etiqueta con el plan afectado y la superficie afectada (física, Shopify o ambas).
- [Getting started](https://docs.perkss.io/api-reference/overview/api-reference.md): Authenticate with an API key, then call the Perkss Partner API over HTTPS.

## API Docs

- Perkss Partner API > Auth [Exchange an API key for an access token](https://docs.perkss.io/api-reference/perkss-partner-api/auth/api-token-exchange.md)
- Perkss Partner API > Auth [Revoke the current access token](https://docs.perkss.io/api-reference/perkss-partner-api/auth/api-token-logout.md)
- Perkss Partner API > Customers [List customers](https://docs.perkss.io/api-reference/perkss-partner-api/customers/list.md)
- Perkss Partner API > Customers [Create a customer](https://docs.perkss.io/api-reference/perkss-partner-api/customers/create.md)
- Perkss Partner API > Customers [Get a customer](https://docs.perkss.io/api-reference/perkss-partner-api/customers/get.md)
- Perkss Partner API > Customers [Get a customer's loyalty state](https://docs.perkss.io/api-reference/perkss-partner-api/customers/loyalty.md)
- Perkss Partner API > Transactions [Record a purchase](https://docs.perkss.io/api-reference/perkss-partner-api/transactions/purchase.md)
- Perkss Partner API > Transactions [Adjust a customer's balance](https://docs.perkss.io/api-reference/perkss-partner-api/transactions/adjustment.md)
- Perkss Partner API > Transactions [Redeem banked rewards](https://docs.perkss.io/api-reference/perkss-partner-api/transactions/redeemreward.md)
- Perkss Partner API > Transactions [List transactions](https://docs.perkss.io/api-reference/perkss-partner-api/transactions/transactions-ledger-list.md)
- Perkss Partner API > Wallet [Mint a wallet pass install link](https://docs.perkss.io/api-reference/perkss-partner-api/wallet/mintpasslink.md)
- Perkss Partner API > Wallet [Get wallet install status](https://docs.perkss.io/api-reference/perkss-partner-api/wallet/getstatus.md)
- Perkss Partner API > Company [Get your company profile](https://docs.perkss.io/api-reference/perkss-partner-api/company/getprofile.md)
- Perkss Partner API > Stores [List stores](https://docs.perkss.io/api-reference/perkss-partner-api/stores/list.md)
- Perkss Partner API > Loyalty Programs [List loyalty programs](https://docs.perkss.io/api-reference/perkss-partner-api/loyalty-programs/loyalty-programs-list.md)
- Perkss Partner API > Statistics [Get loyalty KPIs](https://docs.perkss.io/api-reference/perkss-partner-api/statistics/general.md)
- Perkss Partner API > Statistics [Get the primary chart series](https://docs.perkss.io/api-reference/perkss-partner-api/statistics/graph.md)
- Perkss Partner API > Growth [Get the growth checklist](https://docs.perkss.io/api-reference/perkss-partner-api/growth/checklist.md)
- Perkss Partner API > Notifications [List notification history](https://docs.perkss.io/api-reference/perkss-partner-api/notifications/history.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.perkss.io/openapi.json)
- [OpenAPI YAML](https://docs.perkss.io/openapi.yaml)