Skip to main content
POST
/
subscriptions
/
change-plan
Alterar plano da assinatura
curl --request POST \
  --url https://api.abacatepay.com/v2/subscriptions/change-plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "subs_abc123xyz",
  "productId": "prod_plano_pro",
  "quantity": 1
}
'
{
  "data": {
    "id": "subu_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "status": "PENDING",
    "productId": "prod_plano_pro",
    "quantity": 1,
    "newAmount": 4990,
    "requestedAt": "2024-12-06T20:05:00.000Z"
  },
  "error": null,
  "success": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt

Use this file to discover all available pages before exploring further.

Altera o produto principal de uma assinatura ativa. O novo valor começa a ser cobrado no próximo ciclo de cobrança — o ciclo atual não é afetado.

Requer a permissão SUBSCRIPTION:CREATE.

​
Corpo da requisição

CampoTipoObrigatórioDescrição
idstringSimID da assinatura (subs_...)
productIdstringSimID do novo produto (prod_...) — deve ter ciclo definido
quantityintegerSimQuantidade do produto (mínimo 1)
O produto informado em productId precisa ter um cycle configurado (WEEKLY, MONTHLY, SEMIANNUALLY ou ANNUALLY). Produtos avulsos (sem ciclo) retornam erro.
Exemplo — upgrade de plano: 
{
  "id": "subs_abc123xyz",
  "productId": "prod_plano_pro",
  "quantity": 1
}

​
Resposta

Retorna um objeto de atualização pendente (status: "PENDING"). A mudança é aplicada automaticamente no início do próximo ciclo. 
{
  "data": {
    "id": "subu_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "status": "PENDING",
    "productId": "prod_plano_pro",
    "quantity": 1,
    "newAmount": 4990,
    "requestedAt": "2024-12-06T20:05:00.000Z"
  },
  "success": true,
  "error": null
}
CampoTipoDescrição
idstringID da atualização pendente (subu_...)
subscriptionIdstringID da assinatura
statusstringPENDING até o próximo ciclo; APPLIED após aplicado
productIdstringID do novo produto
quantityintegerQuantidade do produto
newAmountintegerNovo valor em centavos (preço × quantidade)
requestedAtstringData/hora da solicitação
Um evento subscription.plan_changed é disparado imediatamente após a solicitação, com os detalhes do novo plano e o ID da atualização pendente.
Só pode existir uma atualização PENDING por assinatura. Chamar o endpoint novamente sobrescreve a alteração anterior ainda não aplicada.

Authorizations

​
Authorization
string
header
required

Todas as requisições devem incluir sua chave de API no header Authorization usando o formato Bearer <abacatepay-api-key>. Sem esse header a requisição será rejeitada.

Saiba mais sobre como criar e usar chaves de API na documentação de autenticação.

Body

application/json
​
id
string
required

Identificador único da assinatura a ser alterada.

Example:

"subs_abc123xyz"

​
productId
string
required

Identificador do novo produto. Deve ter ciclo de cobrança definido.

Example:

"prod_plano_pro"

​
quantity
integer
required

Quantidade do novo produto.

Required range: x >= 1
Example:

1

Response

Alteração de plano agendada com sucesso.

​
data
object

Atualização de plano pendente de uma assinatura.

​
error
string | null
Example:

null

​
success
boolean

Se a requisição obteve sucesso ou não.

Example:

true