Coleções de Produtos

As coleções de produtos agrupam produtos relacionados (por exemplo, planos Starter, Pro e Enterprise) sob uma mesma estrutura. Exiba todas as opções em um único checkout, defina fluxos de upgrade/downgrade e permita que os clientes troquem de plano diretamente pelo Customer Portal.

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

Principais Destaques

As coleções de produtos permitem:

Agrupar produtos relacionados (planos, níveis e opções de preço) para uma gestão organizada.
Incluir vários produtos, como Starter, Pro e Lifetime, cada um com seu próprio modelo de preços.
Exibir todos os produtos em uma única visualização de checkout, para que os clientes comparem e escolham seu plano preferido.
Permitir que os clientes façam upgrade ou downgrade entre produtos da mesma coleção pelo Customer Portal.
Controlar quais produtos ficam visíveis, em que ordem e qual é pré-selecionado no checkout.

Criando uma coleção de produtos

Crie e gerencie coleções pelo dashboard ou via API.

Create the collection

Defina a coleção com um nome e uma descrição opcional. Faça upload de uma imagem para representá-la no checkout.

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

Campos da coleção:

Nome (obrigatório): Nome de exibição (por exemplo, “Planos SaaS”, “Níveis de licença”).
Descrição (opcional): Breve explicação exibida no checkout.
Imagem (opcional): Identidade visual da coleção.

Add products to the collection

Adicione produtos existentes à sua coleção. Organize-os em grupos para obter uma estrutura melhor.

Captura de tela da página de produtos da coleção, mostrando uma lista de produtos e a possibilidade 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 um 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, remova-o 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 é pré-selecionado automaticamente no checkout. Reordene os produtos para alterar qual será selecionado por padrão.

Checkout da coleção

As coleções permitem uma experiência de checkout unificada, na qual os clientes visualizam e selecionam 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, preços por nível
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 da coleção são exibidos.
O primeiro produto na ordem da coleção é pré-selecionado automaticamente.
Cada produto mostra seu nome, descrição e preço.
O cliente seleciona um produto para comprar.
O checkout continua com os preços e as configurações de cobrança do produto escolhido.

O checkout de coleção é ideal para empresas de assinatura cujos clientes comparam os planos lado a lado antes de comprar.

Integração com a 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'
});

window.location.href = session.checkout_url;

Ao usar product_collection_id, não é possível aplicar códigos de desconto previamente durante a criação da sessão. Os clientes ainda podem inserir códigos durante o checkout, se esse recurso estiver ativado.

Integração com o Customer Portal

Os clientes podem fazer upgrade ou downgrade entre produtos da mesma coleção diretamente pelo Customer Portal.

Você já tem produtos de assinatura? Adicione-os a uma coleção de produtos para ativar fluxos de upgrade/downgrade no Customer Portal. Não é necessário recriar seus produtos.

Ações de gerenciamento de planos

Ação	Descrição	Controle do merchant
Visualizar plano atual	Exibe o nome, o preço e a data de renovação do produto atual.	Sempre disponível.
Fazer upgrade do plano	Migra para um produto de nível superior na mesma coleção.	Configurável (padrão: desativado).
Fazer downgrade do plano	Migra para um produto de nível inferior na mesma coleção.	Configurável (padrão: desativado).
Cancelar	Cancela a assinatura completamente.	Sempre disponível.

Regras de upgrade/downgrade

Upgrades e downgrades só estão disponíveis entre produtos da mesma coleção.
O rateio proporcional para alterações de plano no Customer Portal segue o comportamento padrão de upgrade e downgrade em Settings → Subscriptions, e cada coleção pode substituir esses padrões. As alterações de plano feitas pela Change Plan API usam o proration_billing_mode enviado com a solicitação.
Notificações por e-mail são enviadas à empresa a cada upgrade, downgrade ou cancelamento.

Os clientes não podem mudar para produtos fora da coleção atual. Crie coleções separadas para linhas de produtos distintas.

Configurações de assinatura

Configure como as assinaturas e as alterações de plano funcionam em toda a sua empresa em Settings → Subscriptions, no dashboard.

Configurações disponíveis

Configuração	Descrição	Padrão
Allow Multiple Subscriptions	Os clientes podem ter mais de uma assinatura ativa ao mesmo tempo.	Ativado
Allow Subscription Updates	Os clientes podem fazer upgrade ou downgrade de suas assinaturas existentes a qualquer momento pelo Customer Portal.	Desativado
Allow Immediate Cancellation	Os clientes podem encerrar a assinatura e perder o acesso imediatamente.	Ativado
Allow Cancellation at Next Billing Date	Os clientes podem cancelar ao final do período pelo qual já pagaram.	Ativado
Allow Subscription Pause	Os clientes podem pausar e retomar suas próprias assinaturas pelo Customer Portal.	Desativado
Bill Usage at Pause	Uma assinatura baseada em uso que foi pausada gera uma fatura pelo uso devido no momento da pausa, em vez de transportar o uso para a próxima fatura regular.	Ativado
Prevent Trial Misuse	Clientes que já resgataram um período de avaliação são direcionados para uma compra paga sem período de avaliação, em vez de receberem um novo período de avaliação.	Desativado
Payment Method Reminder	Dias antes do início da cobrança em que o cliente de uma assinatura Card-Optional at Zero Price recebe um e-mail para adicionar uma forma de pagamento (de 1 a 30 dias).	3 dias

As alterações de plano pelo Customer Portal ficam desativadas por padrão. Ative “Allow Subscription Updates” em Settings → Subscriptions para permitir que os clientes façam upgrade ou downgrade entre produtos da mesma coleção.

As duas configurações de cancelamento são independentes. Assim, você pode permitir que os clientes usem o período pelo qual já pagaram e manter o cancelamento imediato disponível apenas para você, ou fazer o inverso. Desativar uma delas oculta essa opção no Customer Portal e rejeita solicitações feitas por ela por meio da Customer Portal API. Os cancelamentos realizados pelo merchant não são afetados. Consulte Cancelando uma assinatura.

“Allow Subscription Pause” controla apenas o Customer Portal — você pode pausar e retomar assinaturas pelo dashboard ou pela API, independentemente dessa configuração. “Bill Usage at Pause” se aplica somente a assinaturas baseadas em uso e é registrado por ciclo de cobrança; portanto, alterá-lo no meio do ciclo não muda a forma como o ciclo em andamento é liquidado. Consulte Pausando e retomando assinaturas.

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

“Payment Method Reminder” só é relevante para assinaturas com Card-Optional at Zero Price ativado — não tem efeito sobre assinaturas que já exigem um cartão. Consulte O que acontece sem um cartão para ver a sequência completa, incluindo o que acontece se o lembrete for ignorado.

Subscription Plan Changes

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

Gerenciando coleções

Gerencie coleções pelo dashboard ou programaticamente via API.

Operações no 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 pode ser desarquivada posteriormente).

Captura de tela do dashboard da coleção de produtos, mostrando as operações de gerenciamento da coleção

Gerenciamento pela API

Use os endpoints a seguir para criar, atualizar, recuperar, arquivar e organizar coleções de produtos programaticamente, incluindo o gerenciamento de grupos e produtos aninhados.

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 da solicitação e da 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 o name e o groups obrigatórios dos produtos, além de detalhes opcionais, como descrição e marca.

Create Product Collection API

Consulte a estrutura detalhada da solicitação e da 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 da solicitação e da 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 da solicitação e da resposta na documentação da API Update Product Collection.

Uploading Collection Images

Associe uma imagem a uma coleção fazendo upload dela por meio de uma URL pré-assinada. Solicite uma URL de upload ao 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 da solicitação e da 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 da solicitação e da 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 da solicitação e da 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 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 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 do grupo: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
Excluir um item do 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 de forma lógica: Organize os produtos por intervalo de cobrança (mensal/anual) ou nível de recursos (starter/pro/enterprise).
Ordene 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 as duas direções: Permita upgrades e downgrades para oferecer flexibilidade aos clientes.
Considere o rateio proporcional: Escolha um modo de rateio proporcional alinhado ao seu modelo de negócios.
Teste completamente: Verifique os fluxos de checkout e de alteração de plano no modo de teste antes de entrar em produção.

Products

Crie produtos avulsos, de assinatura ou baseados em uso para adicionar à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 rateio proporcional e alterações de plano.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Principais Destaques

Criando uma coleção de produtos