> ## 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.
# Coleções de Produtos
> Agrupe produtos relacionados para experiências de checkout unificadas, seleção de planos e caminhos contínuos de upgrade/downgrade no Portal do Cliente.
Coleções de Produtos permitem agrupar produtos relacionados (por exemplo, os planos Starter, Pro e Enterprise) sob um mesmo guarda-chuva. Exiba todas as opções em um único checkout, defina caminhos de upgrade/downgrade e ofereça aos clientes flexibilidade para trocar de plano diretamente no Portal do Cliente.
## Principais Destaques
* **Estrutura baseada em coleções**: Agrupe produtos relacionados (planos, níveis, opções de preços) em uma única coleção para um gerenciamento organizado.
* **Uma coleção, vários produtos**: Inclua múltiplos produtos como Starter, Pro, Lifetime etc., cada um com seu próprio modelo de preços.
* **Experiência de checkout dinâmica**: Exiba todos os produtos de uma coleção em uma única visualização de checkout, permitindo que os clientes escolham o plano preferido.
* **Controle a nível de comerciante**: Ative, desative e reorganize produtos dentro de cada coleção. O primeiro produto é automaticamente pré-selecionado no checkout.
* **Consciência do ciclo de vida**: Permita que os clientes façam upgrade ou downgrade entre produtos da mesma coleção pelo Portal do Cliente.
## Criando uma Coleção de Produtos
Coleções de Produtos são criadas e gerenciadas pelo painel ou via API. Cada coleção funciona como um contêiner para produtos relacionados.
Defina a coleção com um nome e descrição opcional. Faça upload de uma imagem para representar visualmente a coleção no checkout.
**Campos da coleção:**
* **Nome** (obrigatório): Nome exibido para a coleção (por exemplo, "Planos SaaS", "Níveis de Licença")
* **Descrição** (opcional): Breve explicação exibida no checkout
* **Imagem** (opcional): Identidade visual para a coleção
Adicione produtos existentes à sua coleção. Os produtos podem ser organizados em grupos para uma estrutura mais clara.
**Organização dos produtos:**
* **Grupos**: Organize opcionalmente os produtos em grupos nomeados (por exemplo, "Planos Mensais", "Planos Anuais")
* **Produtos sem grupo**: Produtos sem grupo aparecem no nível da coleção
* **Ordenação**: Arraste e solte para definir a ordem de exibição
Cada produto pode pertencer a apenas uma coleção. Se um produto já estiver em outra coleção, será necessário removê-lo primeiro.
Controle a ordem de exibição e a visibilidade dos produtos dentro da coleção.
**Opções de configuração:**
* **Status do produto**: Ative ou desative produtos individuais dentro da coleção
* **Ordem de exibição**: Arraste e solte para definir a sequência em que os produtos aparecem no checkout
O primeiro produto da coleção é automaticamente pré-selecionado como padrão no checkout. Reordene os produtos para alterar qual deles é selecionado por padrão.
## Checkout da Coleção
As coleções permitem uma experiência de checkout unificada onde os clientes podem visualizar e selecionar todos os produtos disponíveis em um só lugar.
### Tipos de Checkout
| Tipo | Descrição | Caso de uso |
| ----------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |
| **Checkout da Coleção** | Exibe todos os produtos ativos dentro de uma coleção | Seleção de planos de assinatura, precificação escalonada |
| **Checkout de Produto Único** | Exibe apenas um produto específico | Compra direta, links promocionais |
### Experiência de Checkout da Coleção
Ao usar um checkout de coleção:
1. **Todos os produtos ativos exibidos**: Os clientes veem cada produto habilitado na coleção
2. **Primeiro produto pré-selecionado**: O primeiro produto na ordem da coleção é automaticamente selecionado
3. **Detalhes do produto exibidos**: Cada produto mostra seu nome, descrição e preço
4. **Seleção única**: O cliente seleciona um único produto para comprar
5. **Fluxo padrão continua**: Após a seleção, o checkout prossegue com os preços e configurações de cobrança do produto escolhido
O checkout de coleção é ideal para negócios por assinatura onde você deseja que os clientes comparem planos lado a lado antes de comprar.
### Integração com API
Crie uma sessão de checkout para uma coleção:
```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;
```
Ao usar `product_collection_id`, códigos de desconto não podem ser aplicados durante a criação da sessão. Os clientes ainda podem inserir códigos de desconto no checkout se essa opção estiver habilitada.
## Integração com o Portal do Cliente
Os clientes podem fazer upgrade ou downgrade entre produtos dentro da mesma coleção diretamente pelo Portal do Cliente.
**Já possui produtos de assinatura?** Basta adicioná-los a uma Coleção de Produtos para habilitar fluxos de upgrade/downgrade no Portal do Cliente. Não é preciso recriar seus produtos.
### Ações de Gerenciamento de Plano
| Ação | Descrição | Controle do comerciante |
| ---------------------------- | ------------------------------------------------------------ | -------------------------------- |
| **Visualizar Plano Atual** | Exibe o nome do produto atual, o preço e a data de renovação | Sempre disponível |
| **Fazer upgrade de plano** | Migrar para um produto de nível superior na mesma coleção | Configurável (padrão: permitido) |
| **Fazer downgrade de plano** | Migrar para um produto de nível inferior na mesma coleção | Configurável (padrão: permitido) |
| **Cancelar** | Cancelar a assinatura completamente | Sempre disponível |
### Regras de Upgrade/Downgrade
* Upgrades e downgrades estão disponíveis apenas entre produtos **dentro da mesma coleção**
* A prorrogação é aplicada com base nas configurações de assinatura
* Notificações por e-mail são enviadas ao negócio em cada upgrade, downgrade ou cancelamento
Clientes não podem mudar para produtos fora de sua coleção atual. Crie coleções separadas para linhas de produtos distintas.
## Configurações de Assinatura
Configure como as assinaturas e alterações de plano funcionam em toda a sua empresa em **Configurações → Assinaturas** no seu dashboard.
### Configurações Disponíveis
| Configuração | Descrição | Padrão |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------- |
| **Permitir Múltiplas Assinaturas** | Clientes podem ter mais de uma assinatura ativa ao mesmo tempo | Ativado |
| **Permitir Atualizações de Assinatura** | Clientes podem fazer upgrade ou downgrade das assinaturas existentes a qualquer momento pelo Portal do Cliente | Desativado |
As alterações de plano via Portal do Cliente estão desativadas por padrão. Ative "Permitir Atualizações de Assinatura" em **Configurações → Assinaturas** para permitir que os clientes façam upgrade ou downgrade entre produtos na mesma coleção.
Saiba mais sobre modos de prorrateio e comportamento de mudança de plano.
## Gerenciando Coleções
As Coleções de Produtos podem ser gerenciadas através do painel de controle do Dodo Payments ou programaticamente via API. A API proporciona controle total sobre a criação de coleções, atualizações, uploads de imagens, arquivamento e gerenciamento de grupos e produtos aninhados.
### Operações de Painel de Controle
* **Criar**: Configure novas coleções com produtos e grupos
* **Atualizar**: Modifique nome, descrição, imagem e organização de produtos
* **Reordenar**: Arraste e solte para alterar a ordem de exibição dos produtos
* **Ativar/Desativar produtos**: Controle quais produtos aparecem no checkout
* **Arquivar**: Oculte uma coleção sem excluí-la permanentemente (pode ser desarquivada posteriormente)
### Gerenciamento via API
Os seguintes endpoints permitem criar, atualizar, recuperar, arquivar e organizar coleções de produtos programaticamente — incluindo o gerenciamento de grupos aninhados e dos produtos dentro deles.
Recupere todas as coleções de produtos associadas à sua conta usando uma solicitação `GET` para o endpoint `/product-collections`. Suporta paginação, filtragem por marca e a inclusão de coleções arquivadas.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Listar Coleções de Produtos.
Crie uma nova coleção de produtos enviando uma solicitação `POST` para o endpoint `/product-collections` com detalhes como nome, descrição e marca.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Criar Coleção de Produtos.
Obtenha informações detalhadas sobre uma coleção de produtos específica — incluindo seus grupos e itens de produto — usando uma solicitação `GET` para o endpoint `/product-collections/{id}`.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Obter Coleção de Produtos.
Modifique os detalhes de uma coleção de produtos (nome, descrição, marca, etc.) enviando uma solicitação `PATCH` para o endpoint `/product-collections/{id}`.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Atualizar Coleção de Produtos.
Associe uma imagem a uma coleção fazendo o upload via uma URL pré-assinada. Solicite uma URL de upload do endpoint `/product-collections/{id}/images`, então `PUT` a imagem para a URL retornada dentro de 60 segundos.
A URL pré-assinada expira em 60 segundos, portanto, a imagem deve ser carregada dentro desse prazo.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Atualizar Imagens da Coleção.
Archive uma coleção enviando uma solicitação `DELETE` para o endpoint `/product-collections/{id}`. Isso oculta a coleção de novos usos, mas não a remove permanentemente.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Arquivar Coleção de Produtos.
Restaure uma coleção arquivada enviando uma solicitação `POST` para o endpoint `/product-collections/{id}/unarchive`.
Veja a estrutura detalhada de solicitação e resposta na documentação da API de Desarquivar Coleção de Produtos.
Os grupos permitem que você organize produtos dentro de uma coleção (por exemplo, "Planos Mensais" vs. "Planos Anuais"). Use os endpoints dos grupos para adicionar, atualizar ou remover grupos dentro de uma coleção.
* **Criar um grupo**: `POST /product-collections/{id}/groups`
* **Atualizar um grupo**: `PATCH /product-collections/{id}/groups/{group_id}`
* **Excluir um grupo**: `DELETE /product-collections/{id}/groups/{group_id}`
Adicione um novo grupo a uma coleção de produtos.
Modifique o nome ou atributos de um grupo.
Remova um grupo de uma coleção.
Gerencie os itens de produto individuais dentro de um grupo — adicione novos produtos, atualize itens existentes (como ordem de exibição) ou remova-os completamente.
* **Adicionar produtos a um grupo**: `POST /product-collections/{id}/groups/{group_id}/items`
* **Atualizar um item de grupo**: `PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}`
* **Excluir um item de grupo**: `DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}`
Adicione um ou mais produtos a um grupo dentro de uma coleção.
Atualize um item de produto dentro de um grupo.
Remova um item de produto de um grupo.
## Melhores Práticas
* **Agrupar logicamente**: Organize os produtos por intervalo de cobrança (mensal/anual) ou nível de recurso (iniciante/pro/enterprise)
* **Ordenar estrategicamente**: Coloque seu plano mais popular ou recomendado primeiro, pois ele será pré-selecionado no checkout
* **Use nomes claros**: Os nomes dos produtos devem comunicar claramente as diferenças de valor
* **Habilitar ambas as direções**: Permita tanto upgrades quanto downgrades para dar flexibilidade aos clientes
* **Considere a prorrogação**: Escolha um modo de prorrogação que se alinhe com o seu modelo de negócios
* **Testar completamente**: Verifique o checkout e os fluxos de mudança de plano no modo de teste antes de ativar
Você está pronto para criar coleções de produtos e oferecer aos clientes uma experiência unificada de seleção de planos.
Crie produtos de cobrança única, assinatura ou baseados em uso para adicionar às coleções.
Exiba os produtos da coleção em uma experiência unificada de checkout.
Permita que os clientes façam upgrades ou downgrades dentro da mesma coleção.
Gerencie planos recorrentes com prorrogação e mudanças de plano.