Criando uma assinatura

Para criar uma assinatura, basta chamar o endpoint de assinaturas.

POST /v3/subscriptions
Confira a referência completa deste endpoint

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "BOLETO",
  "nextDueDate": "2023-10-15",
  "value": 19.9,
  "cycle": "MONTHLY",
  "description": "Assinatura Plano Pró",
}

O campo nextDueDate define quando será feita a primeira cobrança da assinatura, que irá seguir o ciclo conforme configurado. Os ciclos disponíveis são:

WEEKLY - Semanal
BIWEEKLY - Quinzenal (2 semanas)
MONTHLY - Mensal
QUARTERLY - Trimestral
SEMIANNUALLY - Semestral
YEARLY - Anual

A assinatura funciona como um agendador de criação de cobranças. No exemplo acima, uma nova cobrança do tipo boleto será criada mensalmente e enviada ao seu cliente, conforme configurações de notificação.

Depois de criada, você terá em mãos o ID da assinatura que segue um padrão semelhante a este: sub_VXJBYgP2u0eO.

Verificando se uma assinatura foi paga

Para saber se uma assinatura foi paga, você deve acompanhar o webhook para cobranças. Quando uma nova cobrança é criada referente a sua assinatura, você receberá um evento PAYMENT_CREATED e o campo subscription conterá o ID da sua assinatura.

Assim que a cobrança relacionada a assinatura, você receberá o evento PAYMENT_RECEIVED em caso de pagamento por boleto, como no exemplo.

Você também poderá verificar as cobranças criadas de uma assinatura através do endpoint:

GET /v3/subscriptions/{id}/payments
Confira a referência completa deste endpoit

Editar assinatura

É possível alterar todas as informações de uma assinatura do tipo BOLETO ou PIX.

POST /v3/subscriptions/{id}
Veja a referência completa deste endpoint.

Ao atualizar o valor da assinatura ou forma de pagamento somente serão afetadas mensalidade futuras. Para atualizar as mensalidades já criadas mas não pagas com a nova forma de pagamento e/ou novo valor, é necessário passar o parâmetro updatePendingPayments: true.

Recuperar cobranças da assinatura

Diferente de um parcelamento, em que no retorno da criação é devolvido o id da primeira cobrança, no caso de assinaturas, a cobrança é criada apenas depois da assinatura, e não junto, e por isso não é possível recuperar esse id no ato da criação.

Para ter acesso à primeira cobrança criada da assinatura, é necessário consumir a API uma segunda vez no endpoint:

GET /v3/subscriptions/{id}/payments
Veja a referência completa deste endpoint.

Esse endpoint irá retornar todas as cobranças já criadas nesta assinatura, assim como seus status.