Assinaturas

Atualizar Assinatura (Item)

Realiza upgrade ou downgrade de um item da assinatura. Envie old.itemId do item atual e new.priceId (e opcionalmente new.quantity) do novo plano.

Rota canônica para upgrade/downgrade: Atualizar Item (PUT). Este PATCH delega para a mesma lógica.

Upgrade: gera cobrança de pro rata imediatamente (cartão) ou de forma assíncrona via webhook (PIX/boleto). O item antigo só é substituído após confirmação do pagamento.
Downgrade: a mudança é agendada para o próximo ciclo de cobrança, sem cobrança imediata.

Pré-condições: assinatura ACTIVE, PAST_DUE ou AWAITING_PAYMENT; item com status ACTIVE.

Case de uso:

Como SaaS, quero permitir que meu cliente faça upgrade do plano Básico para o Pro no meio do ciclo, cobrando apenas a diferença proporcional.

PATCH/v1/subscriptions/:subscriptionId

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

subscriptions/write

Path Parameters

Name	Type	Required	Description
subscriptionId	string	Required	ID da assinatura (ex: sub_xxx) - required

Body

application/json

Content-Type:application/json

{
  "old": {
    "itemId": "item_xxx"
  },
  "new": {
    "priceId": "price_yyy",
    "quantity": 2
  }
}

Schema

oldobjectRequired

newobjectRequired

← Anterior

Buscar Assinatura

Cancelar Item

const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId';

const options = {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "old": {
    "itemId": "item_xxx"
  },
  "new": {
    "priceId": "price_yyy",
    "quantity": 2
  }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200

{
  "success": true,
  "type": "UPGRADE",
  "chargeId": "cha_xxx",
  "prorataAmount": 45.0,
  "newAmount": 100.0
}

400400

{
    "error": {
        "message": "Cartão recusado por saldo insuficiente",
        "code": "PAYMENT_DECLINED",
        "details": {
            "declinedCode": "insufficient_funds"
        },
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Buscar Assinatura

Cancelar Item