# Faturas de assinatura Saiba como gerenciar faturas de assinatura. Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. *Invoices* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) são recursos essenciais da Stripe, representando o valor devido por um cliente. A Stripe gera uma fatura para cada período de cobrança da assinatura. Você também pode gerar faturas manualmente pelo Dashboard ou pela API para pagamentos únicos ou fora do ciclo. Saiba mais sobre o ciclo de vida de [faturas autônomas](https://docs.stripe.com/invoicing/overview.md#invoice-lifecycle) e [faturas geradas por assinatura](https://docs.stripe.com/billing/invoices/subscription.md#sub-invoice-lifecycle). ## 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](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) a fatura imediatamente quando [collection_method](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-collection_method) estiver definido como `charge_automatically`, ou [uma hora](https://docs.stripe.com/billing/subscriptions/webhooks.md#successful-invoice-finalization) depois quando estiver definido como `send_invoice`. 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](https://docs.stripe.com/api/invoices/object.md#invoice_object-status) e a assinatura se torna ativa. Enquanto o pagamento não é concluído, o [status](https://docs.stripe.com/api/invoices/object.md#invoice_object-status) da fatura permanece `open`, [auto_advance](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md#toggle-auto-advance) permanece `false`, e o [status](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-status) da assinatura permanece `incomplete`. Saiba mais sobre como resolver falhas de pagamento de faturas de novas assinaturas que [exigem uma forma de pagamento](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method). Em alguns casos, o upgrade ou downgrade da assinatura também cria uma fatura. Nessas faturas, desativamos [auto_advance](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md#toggle-auto-advance) desde o início. > 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. 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 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](https://docs.stripe.com/billing/subscriptions/webhooks.md) configurado. Nesse caso, o atributo do [status](https://docs.stripe.com/api/invoices/object.md#invoice_object-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](https://docs.stripe.com/invoicing/automatic-charging.md) a [forma de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) cadastrada, ou [enviando a fatura por e-mail](https://docs.stripe.com/invoicing/integration.md#accept-invoice-payment) aos clientes. Ao tentar coletar o pagamento de uma fatura, a Stripe usa a primeira forma de pagamento disponível nesta lista, nesta ordem: | Prioridade | Forma de pagamento | Atributo da API | | ---------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Forma de pagamento padrão da fatura | [invoice.default_payment_method](https://docs.stripe.com/api/invoices/object.md#invoice_object-default_payment_method) | | 2​ | Forma de pagamento padrão da assinatura | [subscription.default_payment_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) | | 3 | Forma de pagamento padrão do cliente para a fatura | [customer.invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object.md#customer_object-invoice_settings-default_payment_method) | | 4​ | (Legacy) Origem do pagamento padrão do cliente | [customer.default_source](https://docs.stripe.com/api/customers/object.md#customer_object-default_source) | #### Fazer nova tentativa de pagamento A Stripe oferece várias opções para lidar com [pagamentos não efetivados](https://docs.stripe.com/invoicing/automatic-collection.md), incluindo o [Smart Retries](https://docs.stripe.com/invoicing/automatic-collection.md#smart-retries), que usa machine learning. ## Gerenciar faturas de assinatura #### Dashboard As seções a seguir descrevem como realizar [ações básicas em faturas](https://docs.stripe.com/invoicing/dashboard/manage-invoices.md) no Dashboard. ### Criar uma fatura A Stripe cria automaticamente uma [fatura](https://docs.stripe.com/invoicing/dashboard.md#create-invoice) 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](https://docs.stripe.com/invoicing/dashboard/manage-invoices.md#invoice-details-page). ### Ver as próximas faturas A API [Retrieve an invoice](https://docs.stripe.com/api.md#retrieve_invoice) oferece um mecanismo para visualizar uma fatura existente. A Stripe também fornece um endpoint para [criar uma prévia da fatura](https://docs.stripe.com/api/invoices/create_preview.md). 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. #### API Para faturar um cliente com uma cobrança avulsa, como uma tarifa de configuração, crie um [item de fatura](https://docs.stripe.com/api.md#invoiceitems) passando o ID do cliente, a moeda e o preço: ```curl curl https://api.stripe.com/v1/invoiceitems \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "pricing[price]={{PRICE_ID}}" ``` Crie uma fatura para o cliente, e o item é adicionado automaticamente: ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" ``` ## 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-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](https://dashboard.stripe.com/subscriptions). 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**. #### 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. #### Cobrar da forma de pagamento padrão A Stripe finaliza imediatamente a fatura inicial e cobra o cliente. Consequentemente, não há período de uma hora no qual você possa atualizar a fatura inicial antes da finalização. Existem algumas opções disponíveis para fazer alterações na fatura inicial: - Crie a assinatura com `trial_end` definido para vários segundos no futuro. A assinatura primeiro gera uma fatura de US$ 0,00 e, após o término da avaliação, a Stripe cria uma fatura diferente de zero com um período de rascunho de uma hora. O status inicial dessa assinatura é `trialing` e muda para `active` ou `past_due`, dependendo do resultado do pagamento. - Crie a assinatura por meio de uma [programação de assinatura](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#start-subscription-future). Quando a programação começa, o status inicial da assinatura é `active` com um rascunho de fatura inicial agendado para finalizar em uma hora. Dependendo se o pagamento da fatura inicial foi bem-sucedido ou não, a assinatura permanece `active` ou muda para `past_due`. ## Personalizar faturas É possível personalizar faturas de várias maneiras, incluindo: - [Adicionar itens a uma fatura futura](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items) - [Aumentar a frequência das faturas](https://docs.stripe.com/billing/invoices/subscription.md#pending-items-frequently) - [Adicionar itens à primeira fatura de um cliente](https://docs.stripe.com/billing/invoices/subscription.md#first-invoice-extra) - [Adicionar itens a um rascunho de fatura de assinatura](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items) - [Gerar uma fatura fora do período do serviço de assinatura](https://docs.stripe.com/billing/invoices/subscription.md#generating-invoices) - [Suspender uma fatura de assinatura para análise](https://docs.stripe.com/billing/invoices/subscription.md#holding-review) - [Criar uma fatura de assinatura com preços de item configuráveis](https://docs.stripe.com/billing/invoices/subscription.md#invoice-item-prices) ### Adicionar itens a uma fatura futura Você pode adicionar até 250 itens a uma fatura. Para [adicionar itens](https://docs.stripe.com/api/invoiceitems/create.md) à próxima fatura do ciclo: ```curl curl https://api.stripe.com/v1/invoiceitems \ -u "<>:" \ -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 período de cobrança](https://docs.stripe.com/billing/subscriptions/billing-cycle.md), há algumas maneiras de faturar esses itens sem ajustar o período do serviço de assinatura normal: - Crie uma [fatura avulsa](https://docs.stripe.com/invoicing/dashboard.md) para o cliente. - Cobre uma assinatura sempre que o valor devido alcançar um [limite](https://docs.stripe.com/billing/subscriptions/usage-based/thresholds.md). - Use [pending_invoice_item_interval](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-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](https://docs.stripe.com/invoicing/dashboard.md) 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 curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "items[0][price]={{RECURRING_PRICE_ID}}" \ -d "add_invoice_items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete ``` > Se você usa o [Checkout](https://docs.stripe.com/payments/checkout.md) para criar assinaturas, adicione cobranças especificando [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) com a [integração de cliente e servidor](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). ### 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) `invoice.created`. A Stripe [espera aproximadamente uma hora](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand) antes de finalizar a fatura e tentar pagar ou enviar um e-mail. Durante essa espera, a fatura é um [rascunho](https://docs.stripe.com/api/invoices/object.md#invoice_object-status) e pode ser editada. Você pode [criar itens de fatura](https://docs.stripe.com/api/invoiceitems/create.md) nessa fatura. Não se esqueça de informar o parâmetro [invoice](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-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](https://dashboard.stripe.com/customers) 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 período de cobrança Você pode faturar itens pendentes fora do período de cobrança normal [gerando uma fatura avulsa](https://docs.stripe.com/invoicing/dashboard.md). Quando criada, a fatura avulsa incorpora todos os itens de fatura pendentes que seriam adicionados a uma fatura do cronograma normal. > Ao gerar uma fatura manualmente, a Stripe não aplica as [alíquotas](https://docs.stripe.com/billing/taxes/tax-rates.md) que você pode ter definido na assinatura. Se houver incidência de impostos, você deverá [adicionar as alíquotas](https://docs.stripe.com/invoicing/taxes/tax-rates.md) 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: 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](https://dashboard.stripe.com/settings/billing/automatic) 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. 1. Analise a fatura. 1. Assim que estiver tudo pronto para cobrar o cliente, reinicie a cobrança automática. Para isso, defina [auto_advance=true](https://docs.stripe.com/api/invoices/update.md#update_invoice-auto_advance) 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 `active`, 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 [collection_method](https://docs.stripe.com/api/invoices/object.md#invoice_object-collection_method) estiver definido como `charge_automatically` na fatura e a Stripe interromper a cobrança devido ao limite de novas tentativas, o status da assinatura mudará para `canceled`, `unpaid` ou `past_due` com base nas suas [configurações de cobrança automática](https://dashboard.stripe.com/settings/billing/automatic). - Se o [collection_method](https://docs.stripe.com/api/invoices/object.md#invoice_object-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 atender a nenhum desses critérios, o status da assinatura muda para`ativo`. ## Metadados de assinatura Depois que uma assinatura cria uma fatura, ela inclui os `metadata` das seguintes formas: - O atributo [subscription_details.metadata](https://docs.stripe.com/api/invoices/object.md#invoice_object-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 dos [metadados](https://docs.stripe.com/api/invoice/line_item.md#invoice_line_item_object-metadata) dos [itens de linha da fatura](https://docs.stripe.com/api/invoice-line-item/object.md) com [parent.type=“subscription_item_details”](https://docs.stripe.com/api/invoices/object.md#invoice_object-lines-data-parent-type) reflete os `metadados` mais recentes da assinatura no momento da recuperação da fatura, o que significa que eles podem ser diferentes dos `metadados` do momento da criação da fatura. - Os itens de linha da fatura com [parent.type=“invoice_item_details”](https://docs.stripe.com/api/invoices/object.md#invoice_object-lines-data-parent-type) não contêm os `metadata` da assinatura. Quando você modifica diretamente os `metadados` de um item de linha da fatura da assinatura, seja com a [atualização de linha da fatura](https://docs.stripe.com/api/invoice-line-item/update.md) ou com o endpoint [de atualização em massa da linha da fatura](https://docs.stripe.com/invoicing/bulk-update-line-item.md), a solicitação da atualização declara os `metadados` do item de linha da fatura. Nenhum `metadado` “herdado” da assinatura é preservados implicitamente. Os [metadados do item de assinatura](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data-metadata) não são propagados automaticamente para nenhum outro objeto da Stripe.