📘

O que você vai aprender com este artigo?

• Como criar e gerenciar Planos de Assinatura via Alia e API
• Configurações detalhadas para Assinaturas, incluindo valores, ciclos e métodos de pagamento
• Como fazer Upgrade/Downgrade de uma Assinatura e o que é Pró Rata
• Opções para Assinaturas Parceladas e uso do Plano como Motor de Recorrência

A iugu conta com o recurso de Cobrança Recorrente (Assinaturas) que realiza cobranças automáticas e com altíssimo nível de personalização para se adaptar ao seu modelo de negócio.

Plano

Todas as Assinaturas precisam de um Plano previamente criado. Nele, deverão ser informados valores, ciclos, métodos de pagamento (se necessário), os recursos que ele oferece etc.

Para isso, há duas formas:

1. Via Alia

1. Acesse alia.iugu.com > Recebimento > Faturamento Automático (Assinaturas)
2. No canto superior direito > clique em Planos > Novo

3. Preencha as informações:

   Campo	Exemplo	Obs.
   Nome do Plano	Plano Básico	-
   Identificador do Plano	basic_plan	Este será o plan_identifier em chamadas API.
   Tipo de Intervalo	Mês	Também chamado de ciclos.
   Intervalo	2	-
   Valor	10,00	-
   Método(s) que poderá(ão) ser utilizado(s) para aquisição/recorrência	Cartão de Crédito	-
   Número Máximo de Parcelas	2	Disponível apenas para contas que têm Parcelas ativo.

4. Clique em Salvar.

Resultado

Com essa configuração, a Assinatura terá o nome de Plano Básico, com 1 cobrança a cada 2 meses, no valor de R$10,00 e com possibilidade de parcelar em 2x (2x R$5,00).

🚧

Valor mínimo por parcela ⚠️

Para compras parceladas, deve-se respeitar o valor mínimo de R$5,00 por parcela.

2. Via API

Vamos utilizar os mesmos critérios do exemplo acima. Para isso:

1. Utilize o endpoint Criar Plano — POST /v1/plans.

   Informe os parâmetros a seguir no corpo da requisição (itens com * são obrigatórios):

   Parâmetro	Descrição
   name	Nome do Plano
   identifier	Identificador do Plano
   interval	Intervalo/ciclo
   interval_type	Tipo do Intervalo (months ou weeks)
   value_cents	Valor, em centavos, do Plano
   payable_with	Método(s) que poderá(ão) ser utilizado(s) para aquisição/recorrência
   invoice_max_installments	Número máximo de parcelas. Disponível apenas para contas que têm Parcelas ativo.

   Requisição exemplo

curl --request POST \
     --url https://api.iugu.com/v1/plans \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payable_with": [
    "pix"
  ],
  "name": "Plano Básico",
  "identifier": "basic_plan",
  "interval": 2,
  "interval_type": "months",
  "value_cents": 1000,
  "invoice_max_installments": 2
}
'

Assinatura

Apenas com o Plano criado é possível criar uma Assinatura. Então, agora, você associará cobranças recorrentes à um cliente. Para isso, também há duas formas:

1. Via Alia

1. Clique em Recebimento > Faturamento Automático (Assinaturas) > Novo

2. Escolha o Cliente e clique em Criar Assinatura

3. Preencha as informações:

   Campo	Exemplo	Obs.
   Escolha o Plano	Plano Básico
   Insira os itens extras desta assinatura	Item Extra	Além dos que já estão configurados no Plano. Defina o valor desse(s) item(ns). Atenção ⚠️ somarão valor do Plano pré-definido.
   Escolha os métodos de pagamentos	Cartão de Crédito	Se não preenchido, herdará o método configurado no Plano.
   Defina o Limite de Ciclos		Se não marcado, será por tempo indeterminado. E, também, se não preenchido, herdará a configuração do Plano.

4. Clique em Salvar.

2. Via API

Vamos utilizar os mesmos critérios do exemplo acima. Para isso:

1. Utilize o endpoint Criar Assinatura — POST /v1/subscriptions.
2. Informe os parâmetros a seguir:
   1. plan_identifier
   2. customer_id

Requisição exemplo

curl --request POST \
     --url https://api.iugu.com/v1/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "plan_identifier": "basic_plan",
  "customer_id": "282BF13F9DBF4D3D8C5D344FEA370F78"
}
'

Assinatura Parcelada via API

Saiba como criar uma Assinatura Parcelada utilizando as nossas APIs, com a recipe a seguir:

Split por Assinatura

Defina regras de Split de Pagamento específica para cada Assinatura que deseja. Para isso, utilize o objeto splits no endpoint Criar Assinatura — POST /v1/subscriptions.

Requisição exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/subscriptions?api_token=seu-api_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "plan_identifier": "basic_plan",
       "customer_id": "282BF13F9DBF4D3D8C5D344FEA370F78",
       "splits": [
         {
           "recipient_account_id": "account_id",
           "cents": 45
         }
       ]
     }'

Upgrade/Downgrade de Assinatura

É comum que haja mudança de uma assinatura, seja de uma conta Básica para Premium ou vice e versa. Essa mudança é comumente chamada de Upgrade ou Downgrade.

Upgrade/downgrade via API

Para isso, deve-se alterar o Plano da Assinatura. Siga estes passos:

1. Utilize o endpoint Alterar Plano da Assinatura — /v1/subscriptions/{id}/change_plan/{plan_identifier}
2. No URL (path), substitua:
   1. {id} pelo ID da Assinatura que deseja alterar.
   2. {plan_identifier} pelo Identificador do Plano.

Requisição exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/subscriptions/13D9CB0C2DA4427A8D0DAA76F10F4248/change_plan/premium_plan?api_token=your_api_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

🚧

Importante ⚠️

A data da Recorrência (faturamento automático) assumirá a data desta requisição.

Pró Rata

Saiba mais sobre Como funcionam as trocas de planos durante o período de uso?.

Não cobrar Pró Rata

Se não deseja cobrar pró rata nas alterações dos seus planos, utilize o parâmetro skip_charge: true.

E para Assinaturas com Boleto e/ou Pix?

O assinante deve pagar o Boleto ou Pix para, de fato, haver a alteração.

Utilize o Plano apenas para Motor de Recorrência

É possível criar um Plano com valores zerados e utilizá-lo apenas para a criação automática das Faturas, permitindo maior personalização durante a criação das Assinaturas.