Skip to main content
POST
Use POST /subscription/{id}/change-plan para mover um assinante para um plano diferente — seja fazendo upgrade para um nível de preço maior ou downgrade para um menor. Você controla se a mudança entra em vigor de imediato (com o rateio cobrado ou absorvido hoje) ou é programada para o próximo ciclo de faturamento.
O amount, o interval e o intervalCount de um plano são imutáveis assim que ele tem assinantes ativos. Para mudar o preço ou a cadência, crie um novo plano e use este endpoint para migrar assinantes para ele.
planId (plano de destino) é obrigatório; applyAt (now | next_billing, padrão next_billing) controla o momento — veja o painel de parâmetros acima.

​
Resposta

Devolve 200 OK com o objeto de assinatura atualizado. Quando applyAt é "next_billing", a resposta inclui um objeto scheduledPlanChange com o planId e o timestamp effectiveAt.

​
Erros

Se você quer oferecer um período introdutório com desconto no novo plano, crie o novo plano com introAmount e introBillingCycles definidos antes de executar change-plan. O assinante receberá o preço introdutório a partir do primeiro ciclo dele no novo plano.

Autorizações

​
Authorization
string
header
obrigatório

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Parâmetros de caminho

​
id
string
obrigatório

Corpo

application/json
​
merchantCode
string
obrigatório

Your merchant account identifier.

​
planId
integer
obrigatório

ID of the plan to switch to.

​
applyAt
enum<string>

When the change takes effect. next_billing (default) stores it as pending and applies it at the next cycle with no immediate charge. now applies immediately - an upgrade charges the prorated difference by MIT straight away; a downgrade switches immediately with no refund and the lower amount takes effect next cycle.

Opções disponíveis:
now,
next_billing

Resposta

200 - application/json

Plan changed

A customer enrollment in a plan. plan is embedded on single-subscription responses. Invoice/event history is not included here - use the invoice endpoints.

​
id
string

Subscription UUID.

​
merchantId
integer

The merchant account that owns the subscription.

​
planId
integer

ID of the plan this subscription is enrolled in.

​
customerEmail
string

Subscriber email, used for billing and dunning notifications.

​
customerName
string

Subscriber name as it appears on invoices.

​
customerDocument
string

Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ).

​
cardBrand
string

Brand of the card on the mandate, e.g. visa.

​
status
enum<string>

pending - awaiting first charge; trialing - in a free trial; active - billing normally; past_due - a renewal failed and dunning is running; suspended - dunning exhausted, needs a new CIT (POST /subscription/{id}/payment-method in CIT mode) to recover; paused - billing stopped on request, resumable; cancelled - terminated; completed - reached maxBillingCycles.

Opções disponíveis:
pending,
trialing,
active,
past_due,
suspended,
paused,
cancelled,
completed
​
currentPeriodStart
string<date-time>

Start of the current billing period.

​
currentPeriodEnd
string<date-time>

End of the current billing period.

​
nextBillingDate
string<date-time>

When the next renewal charge is scheduled.

​
trialStart
string<date-time>

Trial start, when the plan has a trial.

​
trialEnd
string<date-time>

Trial end - the first real charge date.

​
dunningAttemptCount
integer

Failed-renewal retry attempts made in the current dunning sequence.

​
activatedAt
string<date-time>

When the subscription first became active.

​
cancelledAt
string<date-time>
​
pausedAt
string<date-time>
​
suspendedAt
string<date-time>
​
startAt
string<date-time>

Deferred start, when creation set a future startAt.

​
cyclesCompleted
integer

Number of billing cycles charged so far.

​
completedAt
string<date-time>

When the subscription reached maxBillingCycles.

​
parentSubscriptionId
string

Parent subscription UUID, for add-on hierarchies.

​
propagateLifecycle
boolean

Whether pause/cancel on the parent cascades to this subscription.

​
pendingPlanId
integer

Plan the subscription will switch to at the next cycle, set by a next_billing change-plan.

​
createdAt
string<date-time>
​
updatedAt
string<date-time>
​
plan
object

A reusable billing plan. amount is a flat integer in the currency minor units (with separate currency + exponent) - not an Amount object.