Coleções de Produtos

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.

Captura de tela da página de checkout da Coleção de Produtos mostrando vários produtos exibidos

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.

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.

Captura de tela do formulário de criação da Coleção de Produtos no dashboard mostrando campos para nome, descrição e upload de imagem

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

Add products to the collection

Adicione produtos existentes à sua coleção. Os produtos podem ser organizados em grupos para uma estrutura mais clara.

Captura de tela da página de produtos da Coleção de Produtos mostrando uma lista de produtos e a capacidade de adicioná-los à coleção

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.

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:

Todos os produtos ativos exibidos: Os clientes veem cada produto habilitado na coleção
Primeiro produto pré-selecionado: O primeiro produto na ordem da coleção é automaticamente selecionado
Detalhes do produto exibidos: Cada produto mostra seu nome, descrição e preço
Seleção única: O cliente seleciona um único produto para comprar
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	Os clientes podem ter mais de uma assinatura ativa ao mesmo tempo	Ativado
Permitir atualizações de assinatura	Os clientes podem fazer upgrade ou downgrade de suas assinaturas existentes a qualquer momento via Customer Portal	Desativado
Permitir cancelamento de assinatura	Os clientes podem cancelar suas próprias assinaturas pelo Customer Portal	Ativado
Impedir uso indevido do período de teste	Clientes que já resgataram um período de teste passam a fazer uma compra paga sem período de teste, em vez de receber um novo período de teste	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.

Desativar “Permitir cancelamento de assinatura” oculta dos clientes a opção de cancelamento self-service e rejeita solicitações de cancelamento feitas pela API do Customer Portal. Os cancelamentos realizados pelo seu próprio lado do merchant não são afetados. Consulte Cancelando uma assinatura.

Para obter detalhes sobre como os resgates de períodos de teste são correspondidos e registrados, consulte Impedindo uso indevido do período de teste.

Subscription Plan Changes

Saiba mais sobre os modos de proration e o comportamento das alterações de plano.

Gerenciando coleções

As coleções de produtos podem ser gerenciadas pelo dashboard do Dodo Payments ou programaticamente via API. A API oferece controle total sobre a criação e atualização de coleções, o upload de imagens, o arquivamento e o gerenciamento de grupos aninhados e produtos.

Operações pelo dashboard

Criar: Configure novas coleções com produtos e grupos
Atualizar: Modifique o nome, a descrição, a imagem e a organização dos 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 (ela poderá ser desarquivada posteriormente)

Screenshot of the Product Collection dashboard showing the collection management operations

Gerenciamento pela API

Os endpoints a seguir permitem criar, atualizar, recuperar, arquivar e organizar coleções de produtos programaticamente — incluindo o gerenciamento de grupos aninhados e dos produtos contidos neles.

Listing Product Collections

Busque todas as coleções de produtos associadas à sua conta usando uma solicitação GET para o endpoint /product-collections. Oferece suporte a paginação, filtragem por marca e inclusão de coleções arquivadas.

List Product Collections API

Consulte a estrutura detalhada de solicitação e resposta na documentação da API List Product Collections.

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

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Create Product Collection.

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

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Get Product Collection.

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

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Update Product Collection.

Uploading Collection Images

Associe uma imagem a uma coleção fazendo upload por meio de uma URL pré-assinada. Solicite uma URL de upload do endpoint /product-collections/{id}/images e, em seguida, faça PUT da imagem para a URL retornada em até 60 segundos.

A URL pré-assinada expira em 60 segundos; portanto, a imagem deve ser enviada dentro desse prazo.

Update Collection Images API

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Update Collection Images.

Archiving a Product Collection

Arquive 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

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Archive Product Collection.

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

Consulte a estrutura detalhada de solicitação e resposta na documentação da API Unarchive Product Collection.

Managing Groups within a Collection

Os grupos permitem organizar produtos dentro de uma coleção (por exemplo, “Planos mensais” e “Planos anuais”). Use os endpoints de grupos para adicionar, atualizar ou remover grupos 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 os 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 a 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.

Práticas recomendadas

Agrupe logicamente: Organize os produtos por intervalo de cobrança (mensal/anual) ou nível de recursos (inicial/profissional/empresarial)
Defina a ordem estrategicamente: Coloque o 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
Ative ambas as direções: Permita upgrades e downgrades para oferecer flexibilidade aos clientes
Considere o proration: Escolha um modo de proration alinhado ao seu modelo de negócios
Teste detalhadamente: Verifique os fluxos de checkout e de alteração de plano no modo de teste antes de entrar em produção

Você já pode criar coleções de produtos e oferecer aos clientes uma experiência unificada de seleção de planos.

Products

Crie produtos avulsos, de assinatura ou baseados em uso para adicioná-los às coleções.

Checkout

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

Customer Portal

Permita que os clientes façam upgrade ou downgrade dentro da mesma coleção.

Subscriptions

Gerencie planos recorrentes com proration e alterações de plano.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Principais Destaques

Criando uma Coleção de Produtos