Renovação de Assinatura

Renova uma assinatura finalizada (que completou todos os ciclos contratados), criando uma assinatura nova com o cartão salvo do cliente — sem novo checkout e sem o cliente digitar dados de cartão.


Método	`POST`
Endpoint	`https://api.rockty.com/recurrences/v1/renew`
Content-Type	`application/json`
Autenticação	`Authorization: Bearer <TOKEN>`

Quando usar

Uma assinatura com duração definida (ex.: 12 meses) é finalizada no processador de pagamento ao completar o último ciclo — ela não pode ser reativada nem estendida. Se o cliente quiser continuar, a renovação cria uma assinatura nova a partir da anterior:

Mesmo cartão: usa o cartão salvo (tokenizado) da assinatura anterior — o cliente não precisa informar dados de pagamento.

Mesmo preço: o valor contratado originalmente é mantido (preço congelado).

Mesmo plano: intervalo e quantidade de ciclos iguais aos da assinatura anterior.

Sem trial: a primeira cobrança acontece imediatamente, na própria chamada.

A chamada é síncrona: quando ela retorna com sucesso, a primeira cobrança já foi aprovada e a nova assinatura já está ativa.

Autenticação e escopo

Envie o token no header Authorization (o mesmo usado nas demais rotas da API). A renovação só funciona em assinaturas do próprio tenant do token — nenhum identificador de tenant é enviado no corpo; ele é lido do token.

Requisição

Corpo

{
  "recurrenceId": "ROP12345678"
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`recurrenceId`	`string`	Sim	Identificador da assinatura a renovar. Aceita dois formatos: o id da recorrência ou o id de pesquisa iniciado em `ROP...` (a forma mais comum). O id do pedido inicial completo também é aceito.

Exemplo — cURL

Resposta

Importante: erros de negócio retornam HTTP 200 com o array errors no corpo — o status HTTP não indica o resultado da operação. Trate assim: corpo sem errors = sucesso; corpo com errors = falha (o código do erro vem em errors[0].message). Já 401/403 indicam problema de autenticação (token ausente ou inválido).

Sucesso (HTTP 200, sem `errors`)

{
  "data": {
    "renewSubscription": {
      "newRecurrenceId": "SUB4F7A2C9E",
      "newPreOrderId": "ROP8B3D5F1A",
      "status": "active"
    }
  }
}

Campo	Tipo	Descrição
`data.renewSubscription.newRecurrenceId`	`string`	Identificador da nova assinatura criada pela renovação.
`data.renewSubscription.newPreOrderId`	`string`	Novo id de pesquisa (`ROP...`) da renovação — use este id para consultar a nova assinatura nas demais rotas.
`data.renewSubscription.status`	`string`	Status da nova assinatura. `active` = primeira cobrança aprovada e assinatura ativa.

Falha (HTTP 200, com `errors`)

{
  "errors": [
    {
      "message": "renewal_subscription_not_completed"
    }
  ]
}

Quando errors estiver presente, ignore o conteúdo de data. O código em errors[0].message está na tabela abaixo.

Regras de negócio

Somente assinaturas finalizadas por conclusão dos ciclos. Assinatura ainda ativa/pausada usa os fluxos existentes (troca de cartão, retry etc.); assinatura cancelada não é renovável por esta operação.

Uma renovação por assinatura. Depois de renovada, uma segunda chamada para a mesma assinatura é rejeitada (renewal_already_done). Para renovar de novo no futuro, a chamada deve usar a assinatura nova.

Cobrança imediata. A primeira parcela é cobrada na própria chamada. Se o cartão for recusado, nada é criado do lado da plataforma e a chamada pode ser repetida (ex.: após o cliente regularizar o cartão).

Preço congelado. O valor por ciclo é o contratado na assinatura original — mudanças de precificação do produto não afetam a renovação.

Cartão salvo obrigatório. A renovação usa o cartão tokenizado da assinatura anterior. Se ele não existir mais, o cliente precisa fazer um novo checkout.

Códigos de erro

Código (`errors[0].message`)	Quando acontece	O que fazer
`recurrenceId_is_required`	Campo `recurrenceId` ausente ou vazio.	Enviar o id da assinatura ou o `ROP...`.
`recurrence_not_found`	Id/`ROP` não encontrado no seu tenant.	Confirmar o identificador e o token usado.
`renewal_subscription_not_found`	A assinatura não possui vínculo com o processador de pagamento.	Não renovável — verificar o caso com o suporte.
`renewal_check_unavailable`	Falha temporária ao consultar o processador de pagamento.	Tentar novamente em instantes.
`renewal_subscription_not_completed`	A assinatura ainda está ativa/pausada, ou foi cancelada.	Ativa: usar os fluxos normais (retry, troca de cartão). Cancelada: novo checkout.
`renewal_invalid_status`	A assinatura está cancelada ou pausada na plataforma.	Não renovável por esta operação.
`renewal_already_done`	Esta assinatura já foi renovada antes.	Usar a assinatura nova (retornada na primeira renovação).
`renewal_vaulted_token_not_found`	Não há cartão salvo utilizável na assinatura anterior.	Cliente precisa fazer novo checkout.
`renewal_customer_not_found`	Cadastro do cliente não localizado no processador.	Verificar o caso com o suporte.
`renewal_amount_not_found`	Não foi possível determinar o valor da cobrança.	Verificar o caso com o suporte.
`renewal_payment_declined`	A primeira cobrança foi recusada pelo emissor do cartão.	Nada foi criado. Pode tentar novamente (ex.: após o cliente regularizar o cartão).
`renewal_payment_not_confirmed`	A confirmação da cobrança não chegou no tempo esperado; a assinatura criada foi cancelada por segurança.	Tentar novamente. Se persistir, contatar o suporte.
`renewal_claim_conflict`	Duas renovações simultâneas para a mesma assinatura.	Aguardar e consultar a assinatura — a outra chamada pode ter concluído.

Depois da renovação

A nova assinatura nasce ativa, com o primeiro ciclo pago. As próximas cobranças seguem o intervalo do plano (ex.: mensal), de forma automática.

O pedido e a comissão do primeiro ciclo são registrados normalmente, como uma renovação.

A assinatura anterior permanece no histórico com o status de finalizada — nada nela é alterado ou apagado.

Use o newPreOrderId retornado como identificador da nova assinatura nas demais rotas de consulta — é o mesmo padrão de id (ROP...) já usado hoje.

Renovação de Assinatura

Quando usar#

Autenticação e escopo#

Requisição#

Corpo#

Parâmetros#

Exemplo — cURL#

Resposta#

Sucesso (HTTP 200, sem errors)#

Falha (HTTP 200, com errors)#

Regras de negócio#

Códigos de erro#

Depois da renovação#