Faturas de assinatura

Saiba como gerenciar faturas de assinatura.

Invoices are core resources in Stripe, representing the amount a customer owes. Stripe generates an invoice for every subscription billing period. You can also manually generate invoices through the Dashboard or API for off-cycle or one-time payments. Learn more about the lifecycle for standalone invoices and subscription-generated invoices.

Ciclo da fatura de assinatura

As seções a seguir descrevem como a Stripe processa faturas ao longo do ciclo de vida de uma assinatura.

Faturas de novas assinaturas

Quando você cria uma assinatura para um cliente, a Stripe:

Cria uma fatura.
Finaliza a fatura cerca de uma hora depois.

Se o pagamento da primeira fatura de uma assinatura for bem-sucedido ou se a fatura não exigir pagamento, ela muda para status=paid e a assinatura se torna ativa.

Enquanto o pagamento não é concluído, o status da fatura permanece open, auto_advance permanece false, e o status da assinatura permanece incomplete. Saiba mais sobre como resolver falhas de pagamento de faturas de novas assinaturas que exigem uma forma de pagamento.

Em alguns casos, o upgrade ou downgrade da assinatura também cria uma fatura. Nessas faturas, desativamos auto_advance desde o início.

Em uma fatura finalizada, não é possível adicionar itens nem fazer outras modificações que afetam o valor devido. No entanto, você pode adicionar itens de fatura ao cliente. Os itens adicionados serão aplicados na próxima fatura.

Observação

A Stripe não gera uma fatura quando você cria uma assinatura billing_mode=flexible que contém apenas itens medidos. A assinatura se torna ativa imediatamente. A Stripe gera uma fatura na criação somente se a assinatura estiver atualizada com o uso acumulado anteriormente ou se houver itens de fatura pendentes.

Faturas de renovação de assinatura

Quando uma assinatura é renovada, a Stripe:

Cria uma fatura.
Deixa a fatura no status draft por cerca de uma hora.
Tenta finalizar e pagar a fatura com a forma de pagamento padrão.
Se o pagamento é bem-sucedido, altera o status da fatura para paid.

Quando a Stripe cria uma fatura, você recebe um evento invoice.created no endpoint de webhook configurado. Nesse caso, o atributo do status da fatura é draft, o que significa que os itens da fatura podem ser modificados.

Cobrar pagamentos

Quando uma fatura está vencida, a Stripe tenta recolher o pagamento cobrando automaticamente a forma de pagamento cadastrada, ou enviando a fatura por e-mail aos clientes.

Fazer nova tentativa de pagamento

A Stripe oferece várias opções para lidar com pagamentos não efetivados, incluindo o Smart Retries, que usa machine learning.

Gerenciar faturas de assinatura

As seções a seguir descrevem como realizar ações básicas em faturas no Dashboard.

Criar uma fatura

A Stripe cria automaticamente uma fatura para assinaturas ao final de cada ciclo de cobrança. Finalizamos e enviamos a fatura em uma hora. Você pode editar faturas não finalizadas. Leia mais sobre essas alterações na página de detalhes da fatura.

Ver as próximas faturas

A API Retrieve an invoice oferece um mecanismo para visualizar uma fatura existente. A Stripe também fornece um endpoint para criar uma prévia da fatura. Essa visualização mostra o preço base, os itens de fatura pendentes, os descontos e o saldo de crédito do cliente, se houver.

Ao acessar uma visualização, você também pode modelar a aparência da fatura quando alterá-la de uma destas três formas:

Mudar o preço base.
Alterar a quantidade.
Aplicar um período de avaliação.
Adicionar um cupom.

Atualizar a primeira fatura de uma assinatura

A forma como você edita a primeira fatura de uma assinatura depende da configuração da forma de pagamento da assinatura do cliente. Se não tiver certeza, você pode verificar a configuração da forma de pagamento usando a API ou o Dashboard.

Para verificar a forma de pagamento de uma assinatura usando a API, verifique o valor de collection_method no objeto Subscriptions para o cliente. O valor send_invoice significa que a Stripe envia ao cliente a fatura por e-mail. O valor charge_automatically significa que a Stripe cobra o cliente em seu nome usando a forma de pagamento padrão.

Para verificar a forma de pagamento da assinatura no Dashboard, abra a página Assinatura. Em seguida, clique na assinatura desejada para abrir a visualização detalhada. Na seção Detalhes da assinatura, o valor do campo Método de cobrança define a forma de pagamento: Cobrar forma de pagamento padrão ou Enviar fatura.

Para clientes que recebem faturas, você tem um período de uma hora após a criação até que a Stripe finalize a assinatura. Nesse período, você pode fazer as alterações necessárias na assinatura, como alterar o valor ou os itens de linha, adicionar uma descrição ou metadados e assim por diante.

Após a hora inicial, não é mais possível fazer atualizações. A Stripe envia a fatura por e-mail ao cliente para coletar o pagamento da assinatura.

Personalizar faturas

É possível personalizar faturas de várias maneiras, incluindo:

Adicionar itens a uma fatura futura
Aumentar a frequência das faturas
Adicionar itens à primeira fatura de um cliente
Adicionar itens a um rascunho de fatura de assinatura
Generate an invoice outside of the subscription service period
Suspender uma fatura de assinatura para análise
Criar uma fatura de assinatura com preços de item configuráveis

Adicionar itens a uma fatura futura

Você pode adicionar até 250 itens a uma fatura. Para adicionar itens à próxima fatura do ciclo:

Esses itens isolados são adicionados à próxima fatura criada para esse cliente. Para adicioná-los a uma assinatura específica, use o parâmetro opcional subscription.

Faturar itens pendentes com mais frequência

Other than changing the billing period, there are a few ways to invoice these items without adjusting the normal subscription service period:

Crie uma fatura avulsa para o cliente.
Cobre uma assinatura sempre que o valor devido alcançar um limite.
Use pending_invoice_item_interval para especificar um intervalo e repetir a cobrança de itens de fatura pendentes. Isso equivale a fazer com que a Stripe crie uma fatura avulsa de forma recorrente para a assinatura.

Adicionar uma cobrança à primeira fatura de uma assinatura

Inclua uma cobrança avulsa na primeira fatura de uma assinatura usando add_invoice_items:

Cuidado

Se você usa o Checkout para criar assinaturas, adicione cobranças especificando line_items com a integração de cliente e servidor.

Adicionar itens de fatura a um rascunho de fatura de assinatura

Quando uma assinatura é renovada e cria uma fatura, Stripe envia o evento de webhook invoice.created. A Stripe espera aproximadamente uma hora antes de finalizar a fatura e tentar pagar ou enviar um e-mail.

Durante essa espera, a fatura é um rascunho e pode ser editada. Você pode criar itens de fatura nessa fatura. Não se esqueça de informar o parâmetro invoice ao criar esses itens de fatura. Caso contrário, elas serão adicionadas como itens pendentes e incluídas no próximo período de assinatura.

Esses itens da fatura têm um comportamento ligeiramente diferente dos itens de fatura gerados automaticamente pela Stripe:

Os itens de fatura pendentes são sempre cobrados no final do período de faturamento de assinaturas canceladas. O cancelamento da assinatura de um cliente evita que ele seja cobrado novamente se não houver itens de fatura.
Quando a assinatura de um cliente é alterada, o valor dos itens de fatura pendentes não é recalculado de forma proporcional.

Quando itens de fatura pendentes persistem após o cancelamento de uma assinatura, a Stripe gera uma fatura e tenta cobrar esses itens do cliente no final do próximo período de faturamento. Esses itens de fatura também não são recalculados de forma proporcional quando uma assinatura é alterada.

Gerenciar itens de fatura pendentes

Para ver os itens de fatura pendentes de um cliente, acesse a página Clientes e clique no nome desejado. Os itens são exibidos em Itens de fatura pendentes. Um item de fatura é exibido como pendente quando não está associado a nenhuma fatura.

Em Itens de fatura pendentes, também é possível criar um item de fatura ou faturar imediatamente todos os itens listados. Quando você clica em Faturar agora, o diálogo exibido permite cobrar a origem padrão ou enviar um e-mail com a fatura para o cliente. Além disso, o diálogo oferece a opção de calcular automaticamente os impostos.

Generate an invoice for subscription items outside the billing period

You can invoice pending invoice items outside of the regular billing period by generating a one-off invoice. Generating a one-off invoice pulls in any pending invoice items that would have been added to the regularly scheduled invoice.

Cuidado

Ao gerar uma fatura manualmente, a Stripe não aplica as alíquotas que você possa ter definido na assinatura. Se aplicarem-se impostos, você deverá adicionar as alíquotas explicitamente à fatura.

Suspender uma fatura de assinatura para análise

Em vez de tentar pagar automaticamente uma fatura no final do período de faturamento, você pode suspendê-la para realizar análises ou correções. Para suspender uma fatura:

Suspenda a cobrança automática até uma hora após receber o evento invoice.created. Para fazer isso, defina auto_advance=false na API ou acesse Assinaturas e e-mails no Dashboard. Localize a seção de suspensão de pagamento e clique em Configurar para fazer as alterações. Esse recurso impede a Stripe de cobrar automaticamente a fatura e enviá-la por e-mail ao cliente.
Analise a fatura.
Assim que estiver tudo pronto para cobrar o cliente, reinicie a cobrança automática. Para isso, defina auto_advance=true ou atualize as opções de suspensão de pagamento no Dashboard.

Criar uma fatura de assinatura com preços de item configuráveis

Você pode emitir faturas com preços de itens de linha sem impostos. Os preços sem impostos são mostrados apenas na fatura em PDF. Isso significa que, quando você usa preços com impostos, a página de fatura hospedada e os e-mails de faturas mostram preços com impostos. As configurações dos preços líquidos podem ser definidas no Dashboard ou na API.

Com impostos: a fatura em PDF exibe preços de itens de linha com impostos (configuração padrão).
Sem impostos: a fatura em PDF exibe preços de itens de linha sem impostos.

Precedência de pedidos

Os preços de itens de linha que você define para o cliente têm precedência sobre as configurações da conta.

Anular uma fatura gerada por assinatura

Anular a primeira fatura de uma assinatura

Quando você anula a primeira fatura de uma assinatura, a Stripe aplica a seguinte lógica com base no status da assinatura:

Se a assinatura estiver incomplete, o status da assinatura será alterado para incomplete_expired.
Se a assinatura estiver past_due, o status da assinatura será alterado para active.
Se a assinatura estiver ativa, o status da assinatura não mudará.

Anular a fatura mais recente de uma assinatura

Quando você anula a fatura mais recente de uma assinatura ativa e a fatura não é a primeira, a Stripe aplica a seguinte lógica a cada fatura, começando da mais recente para a mais antiga, até que ela atenda a uma destas condições:

Se a fatura estiver no estado paid ou uncollectible, o status da assinatura mudará para active.
Se o collection_method estiver definido como charge_automatically na fatura e o Stripe tiver parado de cobrar na fatura devido aos limites de novas tentativas, o status da assinatura mudará para canceled, unpaid ou past_due com base nas suas configurações de recolha automática.
Se o collection_method estiver definido como send_invoice e a fatura estiver vencida, o status da assinatura mudará para past_due.
Se a fatura não estiver em um desses status, as mesmas etapas serão executadas na próxima fatura mais recente.

Se nenhuma fatura corresponder a nenhum desses critérios, o status da assinatura mudará para ativo.

Metadados de assinatura

Depois que uma assinatura cria uma fatura, ela inclui os metadata das seguintes formas:

O atributo subscription_details.metadata da fatura sempre contém os metadata da assinatura do momento da criação da fatura, mesmo que os metadata da assinatura sejam modificados posteriormente.
The metadata attribute of invoice line items with parent.type=“subscription_item_details” reflects the most recent subscription metadata at the time of retrieving the invoice, meaning it might differ from the metadata at the time of invoice creation.
Invoice line items with parent.type=“invoice_item_details” don’t contain the subscription’s metadata.

Quando você modifica diretamente os metadata de um item de linha de fatura de assinatura, com a atualização de linha da fatura ou o endpoint de atualização de linha de fatura em lote, a solicitação de atualização declara os metadata do item de linha da fatura. Os metadata de assinatura “herdados” não são preservados implicitamente.

Os metadados do item de assinatura não são propagados automaticamente para nenhum outro objeto da Stripe.