Saldo da fatura do cliente

Saiba como usar o saldo da fatura do cliente.

Todos os clientes no Stripe Billing têm um saldo de fatura no qual você pode fazer ajustes de crédito e débito. Os ajustes no saldo de fatura podem ser um crédito (você deve dinheiro a eles) ou um débito (eles lhe devem dinheiro). Esses ajustes compõem um saldo do cliente que pode ser aplicado a faturas futuras.

Como o saldo da fatura é calculado a partir de um livro-razão (uma lista imutável de transações de débito e crédito), ele proporciona uma trilha de auditoria das transações do cliente. Essas transações de saldo do cliente podem fazer referência ao objeto relacionado ao ajuste (como uma nota de crédito ou ao cliente), ou até mesmo aos metadados para sua própria referência.

Exemplos de casos de uso

Estes são alguns casos de uso comuns para os saldos de faturas de clientes:

Emitir uma nota de crédito para criar um crédito que reduza o valor devido na próxima fatura.
Cálculos pro rata em downgrade de uma assinatura podem criar indiretamente créditos para reduzir o valor devido na próxima fatura.
Quando o valor devido em uma fatura é inferior ao valor mínimo cobrável, a fatura é marcada como paga e o valor devido é transferido para o saldo da fatura como débito. Essa função só existe para clientes sem um cash_balance.

Detalhes do saldo da fatura do cliente

Lembre-se dos seguintes detalhes quando usar saldos de faturas de clientes:

O saldo da fatura é aplicado automaticamente à próxima fatura finalizada para um cliente.
Não é possível escolher uma fatura específica para aplicar o saldo da fatura.
Não é possível optar por não aplicar o saldo da fatura a uma fatura.
O saldo da fatura está na moeda do cliente.
Clientes com saldo em dinheiro não podem manter um saldo positivo, ou seja, não podem aumentar o valor devido na próxima fatura.
O saldo da fatura não se aplica a faturas criadas por sessões do Checkout com invoice_creation ativada.
Não é possível aplicar saldos de fatura a faturas criadas anteriormente que ainda estão em aberto. No entanto, a edição de uma fatura aberta aplica qualquer saldo da fatura à revisão da fatura.

Débitos e créditos

Valores negativos são tratados como créditos (uma redução no valor devido pelo cliente a você) que você pode aplicar na próxima fatura.

Valores positivos são tratados como débitos (um aumento no valor devido pelo cliente a você) que você pode aplicar na próxima fatura.

Transações

Todas as modificações no saldo da fatura são tratadas como transações. Após a criação, só é possível atualizar a description ou metadata, não sendo possível editar outras propriedades ou excluir uma transação.

Desfazer uma transação

Você só pode desfazer uma transação criando uma transação correspondente e reversível. Por exemplo, se você creditar US$ 10 ao cliente, deverá debitar US$ 10 em uma nova transação, em que uma cancela a outra.

Tipos de transação

Todas as transações criadas com a API ou no Dashboard são do tipo adjustment e representam um débito ou crédito que você aplica manualmente para o cliente.

A propriedade type tem vários outros valores possíveis para representar a fonte da criação e o motivo da transação. A tabela a seguir resume e descreve os valores de type:

Tipo	Descrição
`adjustment`	Uma transação de ajuste criada especificamente para debitar ou creditar o saldo da fatura. Esse é o único tipo de transação que você pode criar usando integrações de API e o Dashboard.
`applied_to_invoice`	Rastreia a aplicação de crédito a uma fatura vinculada.
`credit_note`	Rastreia a criação de crédito para uma nota de crédito e a fatura associada.
`invoice_too_small`	Quando o valor devido em uma fatura é inferior ao valor mínimo cobrável da Stripe e o cliente não tem saldo em dinheiro, a fatura é debitada do saldo da fatura e adicionada ao valor devido da próxima fatura emitida.
`invoice_too_large`	Quando o valor devido em uma fatura é superior ao valor máximo cobrável da Stripe e o cliente não tem saldo em dinheiro, a fatura é debitada do saldo da fatura e adicionada ao valor devido da próxima fatura emitida.
`unapplied_from_invoice`	Rastreia a anulação de um saldo de fatura aplicado de uma fatura vinculada. Associado a uma transação `applied_to_invoice` anterior.
`unspent_receiver_credit`	Quando fundos não gastos em fontes do favorecido associados a um cliente sem saldo em dinheiro não são cobrados integralmente depois de 60 dias, a Stripe cobra automaticamente esses fundos em seu nome e credita o seu saldo. Quando isso ocorre, a Stripe também cria uma transação de crédito correspondente.
`initial`	Representa o valor inicial do saldo da fatura do cliente quando o cliente é criado usando a API com um saldo de fatura diferente de zero.

Modificar o saldo da fatura

Você pode modificar o saldo da fatura de um cliente no Dashboard, criando um ajuste de transação de saldo do cliente na página de detalhes do cliente.

Em Saldo da fatura do cliente, clique em Ajustar saldo para exibir o modal Ajuste de saldo de crédito.

Você pode definir informações sobre o ajuste, como:

Tipo de ajuste: escolha crédito ou débito
Moeda: disponível somente se o cliente não tiver uma moeda definida
Quantidade
Observação interna: visível para usuários do Dashboard, mas não para o cliente

Como ajustar o saldo da assinatura de um cliente.

API

Crie ajustes usando a API Customer Balance, como no exemplo de código a seguir.

Histórico de transações de saldo da fatura

Audite os ajustes no saldo da fatura de um cliente no Dashboard, na página de detalhes do cliente, em Saldo da fatura do cliente.

Esta seção exibe o valor atual do saldo da fatura. Clique em Ver detalhes para ver o histórico de transações usado para calcular esse valor. Cada linha de transação exibe os dados do tipo de transação, como um link para a fatura que aplicou o saldo da fatura ou a nota de crédito que creditou o saldo.

Ver o histórico de transações de saldo da fatura

API

Use a Customer Balance List para acessar uma lista de todas as transações de um cliente.

Saldos em dinheiro do cliente

Os clientes que usam a forma de pagamento transferências bancárias têm um objeto cash balance com uma ou mais moedas no objeto available. Você pode usar os fundos para fazer pagamentos ou pagar faturas. Clientes com saldos disponíveis apresentam o seguinte comportamento:

Não é possível criar um saldo negativo de cliente, pois isso representa dinheiro enviado do Customer.
Não é possível finalizar uma fatura muito pequena ou muito grande com o saldo em dinheiro (por exemplo, criando uma assinatura de 0,01 USD). Saiba mais sobre valores mínimos e máximos.
Você pode excluir Customers que têm um saldo em dinheiro, mas somente se o saldo em dinheiro for 0.
Não é possível remover o saldo em dinheiro de um Customer.