Dê autonomia aos assinantes permitindo configurar a assinatura do jeito que eles quiserem.

Alterar Data de Cobrança

Permita que o usuário altere a data de cobrança de sua assinatura. Para isso:

1. Utilize o endpoint Editar Assinatura — PUT /v1/subscriptions/{id}
2. Informe o parâmetro expires_at no body da requisição para a data escolhida
3. No URL (path) substitua {id} pelo ID da Assinatura
4. Faça a requisição

Requisição exemplo

curl --request PUT \
     --url 'https://api.iugu.com/v1/subscriptions/B3F2FE4AA10A433ABB5A1B11C5882C00?api_token=your_api_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "expires_at": "2024-09-25"
}
'

Importante ⚠️

O expires_at será a data da expiração e também da próxima cobrança.

Adicionar/remover itens

Permita que o usuário adicione ou remova itens de sua assinatura. Para isso:

Adicionar ➕

1. Utilize o endpoint Editar Assinatura — PUT /v1/subscriptions/{id}.
2. No body da requisição, informe o objeto subitems e os parâmetros:
   1. description
   2. price_cents
   3. quantity
3. No URL (path) substitua {id} pelo ID da Assinatura.
4. Faça a requisição

Requisição exemplo

{
  "subitems": [
    {
      "description": "Nome do Item",
      "price_cents": "200",
      "quantity": "1",
      "recurrent": false
    }
  ]
}

👍

Será criado um item

Quando este objeto é utilizado, é retornado o id deste item. Guarde-o para removê-lo.

Remover ❌

1. Ainda no mesmo endpoint.
2. No body da requisição, informe o objeto subitem e os parâmetros:
   1. id
   2. _destroy
3. No URL (path) substitua {id} pelo ID da Assinatura.
4. Faça a requisição

Requisição exemplo

{
  "subitems": [
    {
      "id": "5E252FE207F14F4E9AF333694252B2B3",
      "_destroy": true
    }
  ]
}

Adicionar/alterar/remover Método de Pagamento

Permita o usuário editar seus métodos de pagamento de sua assinatura. Antes, certifique-se de seguir as etapas de Tokenização de Cartão de Crédito.

Após isso, continue com estas:

Adicionar ➕

1. Utilize o endpoint Criar Forma de Pagamento — POST /v1/customers/{customer_id}/payment_methods
2. No body da requisição, além dos parâmetro description e token, certifique-se de enviar set_as_default: true

Este cartão será definido como padrão e, os próximos ciclos, serão cobrados nele.

Alterar 📝

1. Utilize o mesmo endpoint e certifique-se de enviar set_as_default: true.

Então, este assumirá as próximas cobranças.

Remover ❌

1. Utilize o endpoint Remover Forma de Pagamento — DELETE /v1/customers/{customer_id}/payment_methods

O método será deletado e, se o usuário quiser utilizá-lo novamente, deverá inserir os dados do cartão novamente.

Suspender Assinatura quando fatura é expirada

Quando o usuário está com uma Assinatura ativa, recebe uma fatura, não paga e ela é expirada (status expired), há a opção de suspendê-la por inadimplência.

Para isso, durante a Criação da Assinatura, informe o parâmetro suspend_on_invoice_expired: true.

Reativar Assinatura

Não é possível pagar uma Fatura expirada, então, para o cliente reativar seu acesso, siga as etapas a seguir:

1. Utilize o endpoint Ativar Assinatura — POST /v1/subscriptions/{id}/activate.
2. No URL (path) substitua {id} pelo ID da Assinatura.
3. Será gerada uma Fatura e o Cliente deverá pagá-la.
4. Após o pagamento a assinatura é reativada.

Desativar lembrete por e-mail sobre vencimento de fatura

Por padrão, são enviados e-mails de lembrete no e-mail do cliente avisando-o sobre o vencimento da fatura. Para desativá-lo, siga esses passos:

1. Utilize o endpoint Editar Assinatura — PUT /v1/subscriptions/{id}.
2. No URL (path) substitua {id} pelo ID da Assinatura.
3. E, no body da requisição, informe o parâmetro ignore_due_email: true.

Assinatura por Créditos

Há modelos de negócios que utilizam créditos (moedas/coins). Para essas assinaturas, durante a criação da Assinatura, no body, informe os parâmetros a seguir:

{
  "credits_based": true,
  "price_cents": 3000,
  "credits_cycle": 300,
  "credits_min": 5
}