> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Colecciones de Productos
> Agrupa productos relacionados para experiencias de pago unificadas, selección de planes y rutas de actualización/diminuación sin problemas dentro del Portal del Cliente.
Las Colecciones de Producto te permiten agrupar productos relacionados (por ejemplo, los planes Starter, Pro y Enterprise) bajo un mismo paraguas. Muestra todas las opciones en un único checkout, define rutas de upgrade/downgrade y ofrece a los clientes la flexibilidad de cambiar de plan directamente desde el Portal del Cliente.
## Puntos Clave
* **Estructura basada en colecciones**: Agrupa productos relacionados (planes, niveles, opciones de precios) bajo una sola colección para una gestión organizada.
* **Una colección, muchos productos**: Incluye múltiples productos como Starter, Pro, Lifetime, etc., cada uno con su propio modelo de precios.
* **Experiencia de pago dinámica**: Muestra todos los productos de una colección en una vista de pago, permitiendo a los clientes elegir su plan preferido.
* **Control a nivel de comerciante**: Habilita, deshabilita y reorganiza productos dentro de cada colección. El primer producto se selecciona automáticamente en el pago.
* **Conciencia del ciclo de vida**: Permite a los clientes actualizar o disminuir entre productos en la misma colección a través del Portal del Cliente.
## Creando una Colección de Productos
Las Colecciones de Productos se crean y gestionan desde el panel de control o a través de API. Cada colección actúa como un contenedor para productos relacionados.
Define la colección con un nombre y una descripción opcional. Sube una imagen para representar visualmente la colección en el checkout.
**Campos de la colección:**
* **Nombre** (requerido): Nombre a mostrar para la colección (por ejemplo, "Planes SaaS", "Niveles de Licencia")
* **Descripción** (opcional): Explicación breve mostrada en el pago
* **Imagen** (opcional): Branding visual para la colección
Añade productos existentes a tu colección. Los productos pueden organizarse en grupos para lograr una mejor estructura.
**Organización de productos:**
* **Grupos**: Organiza opcionalmente productos en grupos nombrados (por ejemplo, "Planes Mensuales", "Planes Anuales")
* **Productos sin agrupar**: Productos sin grupo aparecen a nivel de colección
* **Ordenación**: Arrastra y suelta para establecer el orden de visualización
Cada producto solo puede pertenecer a una colección. Si un producto ya está en otra colección, tendrás que eliminarlo primero.
Controla el orden de visualización y la visibilidad de los productos dentro de la colección.
**Opciones de configuración:**
* **Estado del producto**: Habilita o deshabilita productos individuales dentro de la colección
* **Orden de visualización**: Arrastra y suelta para establecer la secuencia en la que aparecen los productos en el pago
El primer producto de la colección se preselecciona automáticamente como predeterminado en el checkout. Reordena los productos para cambiar cuál se selecciona por defecto.
## Pago de la Colección
Las colecciones permiten una experiencia de pago unificada donde los clientes pueden ver y seleccionar todos los productos disponibles en un solo lugar.
### Tipos de Pago
| Tipo | Descripción | Caso de Uso |
| -------------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| **Pago de Colección** | Muestra todos los productos activos dentro de una colección | Selección de plan de suscripción, precios en capas |
| **Pago de Producto Único** | Muestra solo un producto específico | Compra directa, enlaces promocionales |
### Experiencia de Pago de la Colección
Al usar un pago de colección:
1. **Todos los productos activos mostrados**: Los clientes ven todos los productos habilitados en la colección
2. **Primer producto preseleccionado**: El primer producto en el orden de la colección se selecciona automáticamente
3. **Detalles del producto mostrados**: Cada producto muestra su nombre, descripción y precio
4. **Selección única**: El cliente selecciona un producto para comprar
5. **Flujo estándar continúa**: Después de la selección, el pago procede con los ajustes de precios y facturación del producto elegido
El checkout de colección es ideal para negocios de suscripción donde quieres que los clientes comparen planes lado a lado antes de comprar.
### Integración de API
Crea una sesión de pago para una colección:
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_collection_id: 'pdc_abc123',
product_cart: [], // Required: pass an empty array for collection checkout
return_url: 'https://yoursite.com/return'
});
// Redirect customer to the checkout
window.location.href = session.checkout_url;
```
Cuando uses `product_collection_id`, no se pueden aplicar códigos de descuento al crear la sesión. Los clientes aún pueden introducir códigos de descuento durante el checkout si están habilitados.
## Integración del Portal del Cliente
Los clientes pueden actualizar o disminuir entre productos dentro de la misma colección directamente desde el Portal del Cliente.
**¿Ya tienes productos de suscripción?** Simplemente añádelos a una Colección de Producto para habilitar los flujos de upgrade/downgrade en el Portal del Cliente. No es necesario volver a crear tus productos.
### Acciones de gestión del plan
| Acción | Descripción | Control del comerciante |
| ------------------- | --------------------------------------------------------------------------- | ---------------------------------------- |
| **Ver plan actual** | Muestra el nombre del producto, el precio y la fecha de renovación actuales | Siempre disponible |
| **Actualizar plan** | Cambia a un producto de nivel superior dentro de la misma colección | Configurable (predeterminado: permitido) |
| **Degradar plan** | Cambia a un producto de nivel inferior dentro de la misma colección | Configurable (predeterminado: permitido) |
| **Cancelar** | Cancela la suscripción por completo | Siempre disponible |
### Reglas de upgrade/downgrade
* Las mejoras y degradaciones solo están disponibles entre productos **dentro de la misma colección**
* Se aplica la prorrata según la configuración de suscripción
* Se envían notificaciones por correo electrónico al negocio en cada upgrade, downgrade o cancelación
Los clientes no pueden cambiar a productos fuera de su colección actual. Crea colecciones separadas para líneas de producto distintas.
## Configuración de suscripciones
Configura cómo funcionan las suscripciones y los cambios de plan en tu negocio desde **Configuración → Suscripciones** en tu panel de control.
### Configuración disponible
| Configuración | Descripción | Predeterminado |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Permitir múltiples suscripciones** | Los clientes pueden tener más de una suscripción activa al mismo tiempo | Habilitado |
| **Permitir actualizaciones de suscripción** | Los clientes pueden actualizar o degradar sus suscripciones existentes en cualquier momento a través del Portal del Cliente | Deshabilitado |
Los cambios de plan a través del Portal del Cliente están deshabilitados por defecto. Habilita "Permitir Actualizaciones de Suscripción" en **Configuración → Suscripciones** para permitir a los clientes actualizar o degradar entre productos en la misma colección.
Obtén más información sobre los modos de prorrata y el comportamiento de los cambios de plan.
## Gestión de colecciones
Las colecciones de productos se pueden gestionar a través del panel de control de Dodo Payments o de manera programática mediante la API. La API proporciona control total sobre la creación, actualización, carga de imágenes, archivo y gestión de grupos anidados y productos.
### Operaciones del Dashboard
* **Crear**: Configurar nuevas colecciones con productos y grupos
* **Actualizar**: Modificar nombre, descripción, imagen y organización de productos
* **Reordenar**: Arrastrar y soltar para cambiar el orden de visualización de los productos
* **Habilitar/Deshabilitar productos**: Controlar qué productos aparecen en el checkout
* **Archivar**: Ocultar una colección sin eliminarla permanentemente (puede desarchivarse más tarde)
### Gestión por API
Los siguientes endpoints te permiten crear, actualizar, recuperar, archivar y organizar colecciones de productos de manera programática, incluyendo la gestión de grupos anidados y los productos dentro de ellos.
Obtén todas las colecciones de productos asociadas con tu cuenta usando una solicitud `GET` al endpoint `/product-collections`. Soporta paginación, filtrado por marca e inclusión de colecciones archivadas.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Listar Colecciones de Productos.
Crea una nueva colección de productos enviando una solicitud `POST` al endpoint `/product-collections` con detalles como nombre, descripción y marca.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Crear Colección de Productos.
Obtén información detallada sobre una colección de productos específica, incluyendo sus grupos y artículos de producto, utilizando una solicitud `GET` al endpoint `/product-collections/{id}`.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Obtener Colección de Productos.
Modifica los detalles de una colección de productos (nombre, descripción, marca, etc.) enviando una solicitud `PATCH` al endpoint `/product-collections/{id}`.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Actualizar Colección de Productos.
Asocia una imagen con una colección cargándola a través de una URL pre-firmada. Solicita una URL de carga desde el endpoint `/product-collections/{id}/images`, luego `PUT` la imagen a la URL devuelta dentro de los 60 segundos.
La URL pre-firmada expira en 60 segundos, por lo que la imagen debe cargarse dentro de ese periodo de tiempo.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Actualizar Imágenes de Colección.
Archiva una colección enviando una solicitud `DELETE` al endpoint `/product-collections/{id}`. Esto oculta la colección para nuevo uso, pero no la elimina permanentemente.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Archivar Colección de Productos.
Restaura una colección archivada enviando una solicitud `POST` al endpoint `/product-collections/{id}/unarchive`.
Consulta la estructura detallada de solicitud y respuesta en la documentación de la API de Desarchivar Colección de Productos.
Los grupos te permiten organizar productos dentro de una colección (por ejemplo, "Planes Mensuales" vs. "Planes Anuales"). Usa los endpoints de grupos para añadir, actualizar, o eliminar grupos dentro de una colección.
* **Crear un grupo**: `POST /product-collections/{id}/groups`
* **Actualizar un grupo**: `PATCH /product-collections/{id}/groups/{group_id}`
* **Eliminar un grupo**: `DELETE /product-collections/{id}/groups/{group_id}`
Añadir un nuevo grupo a una colección de productos.
Modificar el nombre o atributos de un grupo.
Eliminar un grupo de una colección.
Gestiona los artículos de productos individuales dentro de un grupo: añade nuevos productos, actualiza artículos existentes (como el orden de visualización) o elimínalos completamente.
* **Añadir productos a un grupo**: `POST /product-collections/{id}/groups/{group_id}/items`
* **Actualizar un artículo del grupo**: `PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}`
* **Eliminar un artículo del grupo**: `DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}`
Añadir uno o más productos a un grupo dentro de una colección.
Actualizar un artículo de producto dentro de un grupo.
Eliminar un artículo de producto de un grupo.
## Mejores Prácticas
* **Agrupar lógicamente**: Organiza los productos por intervalo de facturación (mensual/anual) o nivel de características (inicio/pro/empresa)
* **Ordenar estratégicamente**: Coloca tu plan más popular o recomendado primero, ya que se preseleccionará en el checkout
* **Usar nombres claros**: Los nombres de los productos deben comunicar claramente las diferencias de valor
* **Habilitar ambas direcciones**: Permitir tanto actualizaciones como degradaciones para dar flexibilidad a los clientes
* **Considerar la prorrata**: Elige un modo de prorrata que se alinee con tu modelo de negocio
* **Probar minuciosamente**: Verificar los flujos de checkout y cambio de plan en modo de prueba antes de lanzarlo
Estás listo para crear colecciones de productos y ofrecer a los clientes una experiencia de selección de planes unificada.
Crea productos de un solo uso, suscripción o basados en uso para añadir a las colecciones.
Muestra productos de colección en una experiencia de checkout unificada.
Permitir a los clientes mejorar o degradar dentro de la misma colección.
Gestiona planes recurrentes con prorrateo y cambios de plan.