Faturas de assinatura

As faturas são um recurso essencial na Stripe, representando o valor devido por um cliente. A Stripe gera uma fatura para cada período em um ciclo de cobrança de assinatura. Também é possível gerar faturas manualmente por meio do Dashboard ou da API para pagamentos fora de ciclo ou avulsos. Saiba mais sobre o ciclo de vida de faturas avulsas e faturas geradas por assinaturas.

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.

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.

Faturas de renovação de assinatura

Quando uma assinatura é renovada, a Stripe:

• Cria uma fatura.

• Deixa a fatura no estado 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

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 da assinatura usando a API, verifique o valor de collection_method no objeto Subscriptions do cliente. Um valor de send_invoice significa que a Stripe envia a fatura por e-mail ao cliente. Um valor de charge_automatically significa que a Stripe cobra o cliente em seu nome usando a forma de pagamento padrão dele.

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.

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
• Gerar uma fatura fora do ciclo de assinatura
• 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:

curl https://api.stripe.com/v1/invoiceitems \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "pricing[price]"=price_CBb6IXqvTLXp3f \
  -d customer=cus_4fdAW5ftNQow1a

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

Além de alterar o ciclo de faturamento, existem diferentes maneiras de faturas esses itens sem ajustar o ciclo normal de assinatura:

• 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:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{RECURRING_PRICE_ID}} \
  -d "add_invoice_items[0][price]"={{PRICE_ID}} \
  -d payment_behavior=default_incomplete

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.

Gerar uma fatura para itens de assinatura fora do ciclo de faturamento

Você pode faturar itens pendentes fora do ciclo de faturamento normal gerando uma fatura avulsa. Quando criada, a fatura avulsa incorpora todos os itens de fatura pendentes que seriam adicionados a uma fatura do cronograma normal.

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:

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

2. Analise a fatura.

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

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.
• O atributo metadados de itens de linha de fatura com type=“subscription” reflete os metadata de assinatura mais recentes no momento da recuperação da fatura, o que significa que pode diferir dos metadata no momento da criação da fatura.
• Os itens de linha da fatura com type=“invoiceitem” não contêm os metadata da assinatura.

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.