> ## 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.
# Alterar plano da assinatura
> Altera o produto principal de uma assinatura ativa.
A mudança é agendada como `PENDING` e aplicada automaticamente no início do próximo ciclo de cobrança. Só pode existir uma alteração pendente por assinatura — uma nova chamada substitui a anterior ainda não aplicada.
O produto informado em `productId` deve ter um ciclo de cobrança definido. Produtos avulsos (sem ciclo) retornam erro.
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
| Campo | Tipo | Obrigatório | Descrição |
| ----------- | ------- | ----------- | --------------------------------------------------------- |
| `id` | string | Sim | ID da assinatura (`subs_...`) |
| `productId` | string | Sim | ID do novo produto (`prod_...`) — deve ter ciclo definido |
| `quantity` | integer | Sim | Quantidade 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:**
```json theme={null}
{
"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.
```json theme={null}
{
"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
}
```
| Campo | Tipo | Descrição |
| ---------------- | ------- | ------------------------------------------------------ |
| `id` | string | ID da atualização pendente (`subu_...`) |
| `subscriptionId` | string | ID da assinatura |
| `status` | string | `PENDING` até o próximo ciclo; `APPLIED` após aplicado |
| `productId` | string | ID do novo produto |
| `quantity` | integer | Quantidade do produto |
| `newAmount` | integer | Novo valor em centavos (`preço × quantidade`) |
| `requestedAt` | string | Data/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.
## OpenAPI
````yaml POST /subscriptions/change-plan
openapi: 3.1.0
info:
title: API AbacatePay
description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
version: 1.0.0
servers:
- url: https://api.abacatepay.com/v2
description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
/subscriptions/change-plan:
post:
summary: Alterar plano da assinatura
description: >
Altera o produto principal de uma assinatura ativa.
A mudança é agendada como `PENDING` e aplicada automaticamente no início
do próximo ciclo de cobrança. Só pode existir uma alteração pendente por
assinatura — uma nova chamada substitui a anterior ainda não aplicada.
O produto informado em `productId` deve ter um ciclo de cobrança
definido. Produtos avulsos (sem ciclo) retornam erro.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
- productId
- quantity
additionalProperties: false
properties:
id:
type: string
description: Identificador único da assinatura a ser alterada.
example: subs_abc123xyz
productId:
type: string
description: >-
Identificador do novo produto. Deve ter ciclo de cobrança
definido.
example: prod_plano_pro
quantity:
type: integer
minimum: 1
description: Quantidade do novo produto.
example: 1
responses:
'200':
description: Alteração de plano agendada com sucesso.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/SubscriptionUpdate'
error:
type: string
nullable: true
example: null
success:
$ref: '#/components/schemas/Success'
'401':
description: Não autorizado. Falha na autenticação.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Token de autenticação inválido ou ausente.
'404':
description: Assinatura ou produto não encontrado.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Subscription not found or not active
'422':
description: 'Dados inválidos (ex: produto sem ciclo).'
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Product must have a billing cycle
security:
- bearerAuth: []
components:
schemas:
SubscriptionUpdate:
type: object
description: Atualização de plano pendente de uma assinatura.
required:
- id
- subscriptionId
- status
- productId
- quantity
- newAmount
- requestedAt
additionalProperties: false
properties:
id:
type: string
description: Identificador único da atualização de plano.
example: subu_abc123xyz
subscriptionId:
type: string
description: Identificador da assinatura associada.
example: subs_abc123xyz
status:
type: string
description: Status da atualização.
enum:
- PENDING
- APPLIED
- CANCELLED
example: PENDING
productId:
type: string
description: Identificador do novo produto.
example: prod_plano_pro
quantity:
type: integer
description: Quantidade do novo produto.
example: 1
newAmount:
type: integer
description: >-
Novo valor a ser cobrado por ciclo, em centavos (preço ×
quantidade).
example: 4990
requestedAt:
type: string
format: date-time
description: Data e hora em que a alteração foi solicitada.
example: '2024-12-06T20:05:00.000Z'
Success:
type: boolean
description: Se a requisição obteve sucesso ou não.
example: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Todas as requisições devem incluir sua chave de API no header
Authorization usando o formato `Bearer `. Sem esse
header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na [documentação de
autenticação](/pages/authentication).
````