📘

O que você irá aprender com esse artigo?

• O que pode ser alterado em uma assinatura

Caso de uso

“Quero disponibilizar aos meus clientes, opções de alteração de assinatura como: alterar data de cobrança, acrescentar itens a assinatura, alterar método de pagamento, desabilitar o envio de e-mails notificando o vencimento da fatura, suspender assinatura.”

O que pode ser alterado em uma assinatura

É possível alterar informações de uma assinatura, via API, como:

Data de Cobrança
Para alterar a data de cobrança, é preciso realizar uma atualização na assinatura utilizando o método PUT no endpoint https://api.iugu.com/v1/subscriptions/{id} informando o parâmetro de id da assinatura e expires_at, que é a data de expiração e também a data da próxima cobrança.

Adicionar ou remover itens em uma assinatura
Para acrescentar produtos a assinatura, deve realizar uma atualização na mesma, utilizando o método PUT no endpoint https://api.iugu.com/v1/subscriptions/{id}.

É necessário que informe os parâmetros de id da assinatura e dentro da informação de subitens inserir os dados do produto (descrição, preço em centavos, quantidade e se este item terá ou não recorrência).

Já para remover item de uma assinatura, utilize o método PUT no endpoint https://api.iugu.com/v1/subscriptions/{id} informando dentro do objeto os parâmetros de id do subitem a ser removido e o parâmetro _destroy com o valor de true.

Desabilitar envio de e-mails notificando o vencimento da fatura
É possível realizar a atualização da assinatura para que o cliente não receba e-mail de vencimento da fatura, utilizando o método PUT no endpoint https://api.iugu.com/v1/subscriptions/{id} passando o parâmetro ignore_due_email com o valor de true.

Troca de plano da assinatura
A alteração de plano dentro de uma assinatura há duas formas que podem ser realizadas:

- Cobrando pró-rata
Para maiores informações, consulte a documentação Upgrade e Downgrade de Assinatura.

- Sem cobrança de pró-rata
É preciso realizar a alteração utilizando o método PUT na endpoint https://api.iugu.com/v1/subscriptions/{id} informando o id da assinatura e o plan_identifier como parâmetro básico para alteração.

Porém para não realizar cobrança de pró-rata, é preciso ou alterar a data de cobrança da assinatura, ou passar o parâmetro skip_charge com o valor true, para ignorar a cobrança.

Utilizando o parâmetro skip_charge, não será gerada a cobrança de forma imediata, obedecendo a data da cobrança do ciclo.

Exemplo de request

curl --request PUT \ 
     --url 'https://api.iugu.com/v1/subscriptions/{{subscription_id}}' \ 
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Basic {{api_token in base64}}' \
     --data ' 
{ 
     "two_step": false, 
     "suspend_on_invoice_expired": true, 
     "plan_identifier": "web_plan", 
     "skip_charge": true 
}'

Exemplo de response

É possível realizar a mudança de plano de uma assinatura ativa, para isto veja o artigo: https://dev.iugu.com/docs/upgrade-e-downgrade-de-assinatura

- Alterar método de pagamento da assinatura
Caso seu cliente precise alterar o método de pagamento, criamos um artigo específico: https://dev.iugu.com/docs/alterar-m%C3%A9todo-de-pagamento-de-uma-assinatura

Existem algumas alterações, que não dependem da solicitação do cliente, como

- Habilitar ou desabilitar transação em duas etapas
Esta opção precisa estar habilitada nas configurações da conta na iugu. Para realizar esta alteração utilize o método PUT na endpoint https://api.iugu.com/v1/subscriptions/{id} passando o parâmetro two_step com o valor de true.

Saiba mais sobre cobrança em duas etapas clicando aqui.

- Suspender assinatura quando há fatura expirada

Esta opção te possibilita suspender a assinatura caso a fatura não tenha confirmação de pagamento e expire.
Para atualizar a assinatura, com o intuito de habilitar ou desabilitar esta opção, utilize o método PUT na endpoint https://api.iugu.com/v1/subscriptions/{id} passando o parâmetro suspend_on_invoice_expired com o valor de true.

Exemplo de Request

curl --request PUT \ 
     --url 'https://api.iugu.com/v1/subscriptions/{{subscription_id}}' \ 
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Basic {{api_token in base64}}' \
     --data ' 
{ 
     "subitems": [ 
          { 
               "description": "novo produto", 
               "price_cents": "1500", 
               "quantity": "1", 
               "recurrent": true 
          } 
     ], 
     "two_step": false, 
     "suspend_on_invoice_expired": true, 
     "expires_at": "2021-11-29", 
     "ignore_due_email": false, 
     "suspended": false, 
     "skip_charge": false 
}'

Exemplo de Response