# Pré-cobrança Use pré-faturamento para cobrar agora por vários períodos futuros de serviço. ## Comece aqui: instale skills de agente A Stripe recomenda usar skills oficiais para integrar com a API seguindo práticas recomendadas. Siga as instruções abaixo para saber como. **Dica: use curl em vez de ferramentas Fetch.** Skills são arquivos markdown detalhados de 10 KB a 20 KB. Ferramentas Fetch fazem um resumo deles. `curl -sL` garante o conteúdo completo. **Usando `npx skills`**: verifique se `npx` está instalado no sistema. Se `npx` estiver disponível, execute `npx skills add https://docs.stripe.com --list` para listar os skills disponíveis e, depois, execute `npx skills add https://docs.stripe.com --yes --skill <--skill other-skills>` para instalar skills individuais. **Se `npx skills` não estiver disponível**: é possível usar curl para buscar o índice de skills disponíveis, o que eles fazem e seus arquivos em `https://docs.stripe.com/.well-known/skills/index.json`. Para baixar um skill e os arquivos relacionados, use curl para baixá-los de `https://docs.stripe.com/.well-known/skills/`. Para este artigo, recomendamos usar estes skills: `stripe-best-practices` Com o pré-faturamento, você pode cobrar clientes antecipadamente por vários períodos de serviço. Você pode habilitar o pré-faturamento ao criar uma assinatura ou adicioná-lo a uma assinatura existente. > #### Modo de faturamento flexível obrigatório > > O pré-faturamento exige assinaturas com o [modo de faturamento flexível](https://docs.stripe.com/billing/subscriptions/billing-mode.md) habilitado. Se você ainda não habilitou o modo de faturamento flexível, consulte [Modo de faturamento flexível](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para começar. ## Casos de uso Com o pré-faturamento, você pode cobrar antecipadamente por períodos futuros de serviço. Casos de uso comuns incluem: | Caso de uso | Descrição | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pré-pagamento de vários meses no cadastro** | Cobre antecipadamente de um assinante mensal por 3 meses no momento do cadastro e depois retomar a faturamento mensal normal a partir daí. | | **Faturamento antecipado de renovação** | Quando faltar 7 dias para uma renovação, gere e envie agora a fatura de renovação ao cliente, em vez de esperar o fim do ciclo de faturamento. | | **Pagamento anual em um preço mensal** | Permita que um cliente pague 12 meses de um plano mensal em uma única fatura antecipada, sem alterar o preço subjacente para um intervalo anual. | | **Pré-faturamento em nível de item** | Aplicar pré-faturamento a um item adicional específico enquanto outros itens da mesma assinatura continuam sendo cobrados na cadência mensal normal. | | **Tarifa de cancelamento antecipado** | Cobre do cliente o período restante de um contrato com compromisso mínimo quando ele cancelar antecipadamente, aplicando pré-faturamento até o fim do compromisso e depois cancelando a assinatura. | ### Limitações O pré-faturamento possui as seguintes limitações: - Você não pode usar pré-faturamento com [cronogramas de assinatura](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) nem com assinaturas vinculadas a um cronograma de assinatura. - Você só pode usar cupons com [percent_off](https://docs.stripe.com/api/coupons/object.md#coupon_object-percent_off) e [duração](https://docs.stripe.com/api/coupons/object.md#coupon_object-duration) `once` ou `forever` com pré-faturamento. - Você não pode habilitar pré-faturamento se todos os itens da assinatura tiverem preços baseados em uso. O pré-faturamento não se aplica a preços baseados em uso em uma assinatura. Não é possível definir [applies_to[price]](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_schedules-applies_to) se o preço tiver [usage_type=metered](https://docs.stripe.com/api/prices/object.md#price_object-recurring-usage_type). - Se uma assinatura estiver programada para cancelamento, você não poderá definir a data final do pré-faturamento após a data programada de cancelamento. ## Como funciona o pré-faturamento O pré-faturamento usa [billing_schedules](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_schedules) em uma assinatura para definir quais itens serão cobrados antecipadamente e por quanto tempo. Quando você configura `billing_schedules`, a Stripe gera uma fatura antecipada cobrindo todos os períodos futuros de serviço especificados no momento em que a assinatura é criada ou atualizada, em vez de esperar cada ciclo de faturamento ocorrer. O pré-faturamento se aplica no nível do [item](https://docs.stripe.com/api/subscription_items.md): você pode aplicar pré-faturamento a itens específicos usando o parâmetro `applies_to` com os IDs de preços desejados, ou omitir totalmente `applies_to` para aplicar pré-faturamento a todos os itens elegíveis com preço licenciado da assinatura. Preços baseados em uso nunca são incluídos no pré-faturamento, independentemente da configuração de `applies_to`. O parâmetro [bill_until](https://docs.stripe.com/api/subscriptions/update.md?api-version=preview#update_subscription-billing_schedules-bill_until) controla a data final do período pré-faturado. Você pode defini-lo como uma `duração` (por exemplo, 2 meses a partir da data atual) ou como um `timestamp` (um timestamp Unix específico). ## Crie uma assinatura com pré-faturamento Para configurar pré-faturamento ao criar uma assinatura, use [billing_schedules](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_schedules) para especificar quais itens serão pré-faturados e por quanto tempo. - Use `applies_to` para especificar quais itens serão pré-faturados por ID de preço. Omita esse parâmetro para aplicar pré-faturamento a todos os itens elegíveis. - Use `bill_until` para definir a data final do pré-faturamento como duração ou timestamp. - Use `proration_behavior` para controlar quando a fatura de pré-faturamento será gerada. Ao definir a data final do pré-faturamento: - A data final deve ocorrer na data ou após o fim do primeiro período de cobrança. Por exemplo, em uma assinatura mensal, a data final deve ser de pelo menos um mês após o início do período de faturamento. - O total de ciclos pré-faturados entre todos os itens não pode exceder 50. Por exemplo, com dois itens, você pode pré-faturar cada um por até 25 meses. - A data final não pode ultrapassar 5 anos a partir da data atual. #### Dashboard Para criar uma assinatura com pré-faturamento no Dashboard: 1. Acesse a [página Subscriptions (Assinaturas)](https://dashboard.stripe.com/subscriptions?status=active). 2. Clique em **+ Criar assinatura**. 3. Na seção **Subscription settings** (Configurações da assinatura), habilite **Bill upfront** (Cobrar antecipadamente). 4. Selecione a data final do pré-faturamento. Todos os itens da assinatura serão pré-faturados até a data selecionada. 5. Na seção **Advanced settings** (Configurações avançadas), defina o **Billing mode** (Modo de faturamento) como **Flexible** (Flexível). 6. Clique em **Create subscription** (Criar assinatura). Para atualizar uma assinatura existente: > A assinatura já deve estar com `billing_mode=flexible` para habilitar o pré-faturamento. Consulte [Limitações](https://docs.stripe.com/billing/subscriptions/prebilling.md#limitations) para mais detalhes. 1. Acesse a [página Subscriptions (Assinaturas)](https://dashboard.stripe.com/subscriptions?status=active). 2. Clique na assinatura que deseja atualizar e depois selecione **Actions** (Ações) > **Update subscription** (Atualizar assinatura). 3. Na seção **Subscription settings** (Configurações da assinatura), habilite **Bill upfront** (Cobrar antecipadamente). 4. Selecione a data final do pré-faturamento. Todos os itens da assinatura serão pré-faturados até a data selecionada. 5. Clique em **Update subscription** (Atualizar assinatura). #### API ### Pré-faturar um item específico Para aplicar pré-faturamento a um preço específico em uma assinatura, envie um array `applies_to` com o ID do preço que deseja pré-faturar: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ --data-urlencode "items[1][price]={{PRICE_1, PRICE_2}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][applies_to][0][type]=price" \ -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][applies_to][0][type]=price" \ -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` ### Pré-faturar vários itens Para aplicar pré-faturamento a vários itens, adicione vários objetos ao array `applies_to`: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][applies_to][0][type]=price" \ -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \ -d "billing_schedules[0][applies_to][1][type]=price" \ -d "billing_schedules[0][applies_to][1][price]={{PRICE_ID}}" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][applies_to][0][type]=price" \ -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \ -d "billing_schedules[0][applies_to][1][type]=price" \ -d "billing_schedules[0][applies_to][1][price]={{PRICE_ID}}" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` ### Pré-faturar todos os itens Para aplicar pré-faturamento a todos os itens elegíveis, omita o array `applies_to`. O pré-faturamento será aplicado a todos os itens da assinatura com preço licenciado que tenham pelo menos um ciclo antes da data final do pré-faturamento. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` ### Pré-faturar por uma duração Para aplicar pré-faturamento por uma duração específica a partir da data atual, defina `type` como `duration` e configure `interval` e `interval_count`. Por exemplo, para aplicar pré-faturamento por 2 meses, defina `interval` como `month` e `interval_count` como `2`. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` ### Pré-faturar até um timestamp Para aplicar pré-faturamento até uma data específica, defina `type` como `timestamp` e configure `timestamp` com o timestamp Unix correspondente ao fim do pré-faturamento. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` ### Gere a fatura imediatamente Para gerar a fatura de pré-faturamento imediatamente ao criar ou atualizar a assinatura, defina `proration_behavior` como `always_invoice`: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d proration_behavior=always_invoice \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d proration_behavior=always_invoice \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` ### Gere a fatura no próximo ciclo de faturamento Para gerar a fatura de pré-faturamento na próxima data natural do ciclo de faturamento, defina `proration_behavior` como `create_prorations`: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d proration_behavior=create_prorations \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` #### Customer v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[1][price]={{PRICE_ID}}" \ -d "billing_mode[type]=flexible" \ -d proration_behavior=create_prorations \ -d "billing_schedules[0][bill_until][type]=timestamp" \ -d "billing_schedules[0][bill_until][timestamp]=1679609767" ``` ## Atualize uma assinatura existente com pré-faturamento Para adicionar pré-faturamento a uma assinatura existente, atualize a assinatura usando o parâmetro `billing_schedules`. A assinatura já deve estar com `billing_mode=flexible`. ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -d "billing_schedules[0][bill_until][type]=duration" \ -d "billing_schedules[0][bill_until][duration][interval]=month" \ -d "billing_schedules[0][bill_until][duration][interval_count]=2" ``` ## Tarifas de cancelamento antecipado Use o pré-faturamento para cobrar clientes pelo período restante de um contrato com compromisso mínimo quando cancelarem antecipadamente. Isso é comum em assinaturas de prazo fixo cobradas de forma recorrente, por exemplo, mensalmente. Por exemplo, um cliente se cadastra em 1º de janeiro em um plano mensal de US$ 10/mês com duração de 1 ano. Ele cancela em 10 de setembro. Para cobrar o compromisso restante, aplique pré-faturamento da assinatura até dezembro na fatura final e depois cancele a assinatura sem pro rata. 1. [Atualize a assinatura](https://docs.stripe.com/api/subscriptions/update.md) para definir `billing_schedules.bill_until` como o fim do período comprometido (31 de dezembro). 2. [Cancele a assinatura com ](https://docs.stripe.com/api/subscriptions/cancel.md)`proration_behavior` definido como `none`. A fatura final do cliente incluirá cobranças referentes a outubro, novembro e dezembro, cobrindo o restante do compromisso como tarifa de cancelamento antecipado. Esse padrão também funciona para contratos mais longos (por exemplo, um contrato de 2 anos em que o cliente cancela no mês 18) e para cenários de renovação antecipada em que clientes fazem upgrade no meio do período e pagam antecipadamente o restante do prazo no novo preço. ## Considerações adicionais ### Momento de geração da fatura A fatura de pré-faturamento é gerada quando você cria ou atualiza uma assinatura com `billing_schedules` configurado. O momento exato depende da configuração de `proration_behavior`: - `always_invoice`: gera e finaliza a fatura de pré-faturamento imediatamente quando a assinatura é criada ou atualizada. - `create_prorations`: gera a fatura de pré-faturamento na próxima data natural do ciclo de faturamento. Use `always_invoice` se quiser que o cliente receba a fatura antecipada imediatamente. Use `create_prorations` se quiser que a fatura apareça junto da fatura regular do cliente na próxima data de faturamento. ### Webhooks e eventos O pré-faturamento gera faturas fora do ciclo normal de faturamento. Certifique-se de que sua integração trate os eventos relevantes. Por exemplo, você pode querer enviar um recibo ao cliente quando a fatura de pré-faturamento for paga ou tratar falhas de pagamento com um fluxo de nova tentativa. | Evento | Descrição | Caso de uso | | ------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | `invoice.created` | Enviado quando a Stripe gera a fatura de pré-faturamento. | Registre a cobrança antecipada no seu sistema. | | `invoice.finalized` | Enviado quando a fatura é finalizada e está pronta para pagamento. | Acione fluxos de notificação ao cliente. | | `invoice.payment_succeeded` | Enviado quando o pagamento da fatura de pré-faturamento é concluído com sucesso. | Conceda ao cliente acesso aos períodos de serviço pré-pagos. | | `invoice.payment_failed` | Enviado quando o pagamento da fatura de pré-faturamento falha. | Trate a falha de pagamento: lógica de nova tentativa, notificação ao cliente ou pausa da assinatura. | | `customer.subscription.updated` | Enviado quando a assinatura é atualizada com uma nova configuração de `billing_schedules`. | Sincronize o estado atualizado da assinatura com seu sistema. | ### Visualize a fatura de pré-faturamento Você pode visualizar a fatura do cliente antes de criar ou atualizar uma assinatura para usar pré-faturamento. Use a API para [criar uma prévia da fatura](https://docs.stripe.com/api/invoices/create_preview.md) e inclua [billing_schedules](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-subscription_details-billing_schedules) no parâmetro `subscription_details`. Isso mostrará a fatura gerada para o pré-faturamento. ### Interação com cupons Somente cupons com `percent_off` e `duração` `once` ou `forever` são compatíveis com pré-faturamento. Cupons `amount_off` e cupons com `duration=repeating` retornam erro quando usados com uma assinatura que possui `billing_schedules` configurado. ## See also - [Modo de faturamento flexível](https://docs.stripe.com/billing/subscriptions/billing-mode.md) - [Pro ratas](https://docs.stripe.com/billing/subscriptions/prorations.md) - [Pré-visualizar faturas](https://docs.stripe.com/api/invoices/create_preview.md) - [Ciclo de faturamento da assinatura](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)