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.

1. Create the collection

   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
2. Add products to the collection

   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.

3. Configure ordering and visibility

   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:

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.

Subscription Plan Changes

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.

Listing Product Collections

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.

List Product Collections API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Listar Coleções de Produtos.

Creating a Product Collection

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.

Create Product Collection API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Criar Coleção de Produtos.

Retrieving a Product Collection

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}.

Get Product Collection API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Obter Coleção de Produtos.

Updating a Product Collection

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}.

Update Product Collection API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Atualizar Coleção de Produtos.

Uploading Collection Images

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.

Update Collection Images API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Atualizar Imagens da Coleção.

Archiving a Product Collection

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.

Archive Product Collection API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Arquivar Coleção de Produtos.

Unarchiving a Product Collection

Restaure uma coleção arquivada enviando uma solicitação POST para o endpoint /product-collections/{id}/unarchive.

Unarchive Product Collection API

Veja a estrutura detalhada de solicitação e resposta na documentação da API de Desarquivar Coleção de Produtos.

Managing Groups within a Collection

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}

Create Group

Adicione um novo grupo a uma coleção de produtos.

Update Group

Modifique o nome ou atributos de um grupo.

Delete Group

Remova um grupo de uma coleção.

Managing Products within a Group

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}

Add Products to Group

Adicione um ou mais produtos a um grupo dentro de uma coleção.

Update Group Item

Atualize um item de produto dentro de um grupo.

Delete Group Item

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.

Products

Crie produtos de cobrança única, assinatura ou baseados em uso para adicionar às coleções.

Checkout

Exiba os produtos da coleção em uma experiência unificada de checkout.

Customer Portal

Permita que os clientes façam upgrades ou downgrades dentro da mesma coleção.

Subscriptions

Gerencie planos recorrentes com prorrogação e mudanças de plano.