Executar upgrade ou downgrade de plano

Executa a troca de plano de uma assinatura. A direção (upgrade ou downgrade) é determinada automaticamente pela comparação de preço entre o plano atual e o novo plano.

Upgrade: cobra a diferença proporcional imediatamente, no cartão salvo da assinatura (payment_choice=current) ou em um novo cartão informado no corpo da requisição (payment_choice=new_card).
Upgrade no cartão aprovado, mas sem a troca concluída na hora (por exemplo, falha no gateway ao atualizar o plano): a resposta é 200 com upgrade.status pending, e a venda da diferença continua em PROCESSING. A troca é confirmada quando o gateway avisa o pagamento; nesse momento a venda passa a PAID e o webhook TRANSACTION_PAID é enviado. Não cobre de novo.
Downgrade: não gera cobrança imediata; é agendado para entrar em vigor na próxima renovação da assinatura.

O header Idempotency-Key é obrigatório. Em caso de timeout, reenvie a requisição com a mesma chave: a resposta original será devolvida sem processar a troca duas vezes.

Sem campo de autorização: o portal autentica por você com a sua chave de Homologação e as requisições rodam só no ambiente de testes.

Authorization

AuthorizationBearer <token>

Token de acesso devolvido por POST /auth/token. Envie como "Authorization: Bearer ". Vale 24 horas.

In: header

Path Parameters

idstring

Formatuuid

Header Parameters

Idempotency-Keystring

Lengthlength <= 255

Request Body

new_product_price_idstring

Formatuuid

payment_choice?string

Só é relevante para upgrade. Ignorado em downgrade.

Default"current"

Value in"current" | "new_card"

card?object

Obrigatório somente quando payment_choice=new_card

Response Body

curl -X POST "https://pagpolar-api.creativecode.dev.br/v1/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/plan-change" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "new_product_price_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "payment_choice": "current"
  }'

curl -X POST "https://pagpolar-api.creativecode.dev.br/v1/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/plan-change" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "new_product_price_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",    "payment_choice": "current"  }'

{
  "data": {
    "type": "UPGRADE",
    "upgrade": {
      "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "charge_amount": 49.9,
      "status": "pending",
      "pix": {
        "qr_code": "00020126..."
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}