Trocar de plano

Liste as ofertas disponíveis

Chame GET /subscriptions/{id}/plan-options:

curl "https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-options" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

const response = await fetch(
  'https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-options',
  {
    headers: { Authorization: `Bearer ${accessToken}` },
  },
);

console.log(response.status, await response.json());

Resposta resumida:

{
  "data": {
    "allow_client_plan_change": true,
    "current_product_price_id": "<ID_DA_OFERTA_ATUAL>",
    "options": [
      {
        "id": "<ID_DA_OFERTA_ATUAL>",
        "title": "Plano Básico",
        "price": 49.9,
        "is_active": true,
        "cycle": "MONTHLY",
        "cycle_interval": 1
      },
      {
        "id": "<ID_DA_NOVA_OFERTA>",
        "title": "Plano Premium",
        "price": 99.9,
        "is_active": true,
        "cycle": "MONTHLY",
        "cycle_interval": 1
      }
    ]
  }
}

Como ler a resposta:

• allow_client_plan_change é false: o produto não permite troca. A execução vai responder 403. Pare aqui ou ligue a opção no painel.
• options traz as ofertas do mesmo produto que estão ativas e marcadas como selecionáveis.
• options sempre inclui a oferta atual, mesmo que ela não seja mais selecionável. Esconda do cliente a opção cujo id é igual a current_product_price_id.
• A lista não é filtrada por preço. Uma oferta com o mesmo preço da atual aparece, mas a troca para ela responde 400.

Calcule o valor da troca

Mostre ao cliente quanto ele vai pagar antes de trocar. Chame POST /subscriptions/{id}/plan-change/preview com o id da oferta escolhida em new_product_price_id.

Esta chamada não muda nada na assinatura e não cobra nada.

curl -X POST "https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-change/preview" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_product_price_id": "<ID_DA_NOVA_OFERTA>"
  }'

const response = await fetch(
  'https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-change/preview',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      new_product_price_id: '<ID_DA_NOVA_OFERTA>',
    }),
  },
);

console.log(response.status, await response.json());

Resposta de um upgrade. Os números são ilustrativos:

{
  "data": {
    "type": "UPGRADE",
    "current_product_price_id": "<ID_DA_OFERTA_ATUAL>",
    "current_price": 49.9,
    "new_product_price_id": "<ID_DA_NOVA_OFERTA>",
    "new_price": 99.9,
    "total_days": 30,
    "remaining_days": 15,
    "prorated_credit": 24.95,
    "charge_amount": 74.95,
    "effective_at": "2026-09-15T14:00:00.000Z",
    "current_payment_method": "CREDIT_CARD"
  }
}

A conta do upgrade está em Como o valor do upgrade é calculado.

Execute a troca

Chame POST /subscriptions/{id}/plan-change. Envie o header Idempotency-Key, uma chave por troca. Veja Idempotência.

Em downgrade, não envie payment_choice nem card: nada é cobrado.

O exemplo cobra o upgrade no meio de pagamento atual. Ele também serve para downgrade:

curl -X POST "https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-change" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Idempotency-Key: 7c1e2f3a-4b5c-4d6e-8f90-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "new_product_price_id": "<ID_DA_NOVA_OFERTA>"
  }'

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID();

const response = await fetch(
  'https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/plan-change',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      new_product_price_id: '<ID_DA_NOVA_OFERTA>',
    }),
  },
);

console.log(response.status, await response.json());

A resposta é 200. O conteúdo depende do tipo da troca.

Downgrade:

{
  "data": {
    "type": "DOWNGRADE"
  }
}

Upgrade pago na hora, no cartão:

{
  "data": {
    "type": "UPGRADE",
    "upgrade": {
      "transaction_id": "<ID_DA_VENDA_DA_DIFERENCA>",
      "charge_amount": 74.95,
      "status": "paid"
    }
  }
}

Upgrade pendente, em PIX:

{
  "data": {
    "type": "UPGRADE",
    "upgrade": {
      "transaction_id": "<ID_DA_VENDA_DA_DIFERENCA>",
      "charge_amount": 74.95,
      "status": "pending",
      "pix": {
        "qr_code": "<CODIGO_PIX_COPIA_E_COLA>"
      }
    }
  }
}

Em boleto, no lugar de pix vem boleto com barcode (o código do boleto como o gateway devolveu) e pdf_link (link do PDF).

Guarde upgrade.transaction_id. É o id da venda da diferença.

Confirme o resultado

Upgrade com status: "paid". A troca já foi feita. Consulte GET /subscriptions/{id} e confira:

• offer.id é o id da nova oferta;
• next_billing_amount é o preço da nova oferta;
• next_billing_at foi recalculado: o novo ciclo começa no dia da troca;
• status é ACTIVE.

Upgrade com status: "pending". Espere o webhook TRANSACTION_PAID com data.transaction.id igual ao upgrade.transaction_id. Quando ele chegar, consulte a assinatura e confira os mesmos campos do caso paid.

Sem webhook, consulte a venda em GET /sales/{identifier} usando o upgrade.transaction_id. Quando status for PAID, consulte a assinatura.

Se o cliente não pagar, a assinatura continua no plano atual.

Downgrade. Nada muda agora:

• GET /subscriptions/{id} continua mostrando a oferta e o valor atuais até a renovação.
• A troca é aplicada quando a cobrança da próxima renovação é paga. A partir daí, offer passa a ser a nova oferta.
• Na assinatura no cartão, a PagPolar já informa o novo valor ao gateway no momento do agendamento.

Duas regras sobre trocas agendadas:

• Um novo downgrade substitui o downgrade agendado antes.
• Um upgrade confirmado cancela o downgrade agendado.