Dashboard

Plano e itens

Adicionar item

Adiciona um produto à assinatura: um adicional cobrado todo ciclo (RECURRING) ou uma cobrança única (ONE_TIME).

POST/v1/subscriptions/:subscriptionId/items
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

O que acontece com a cobrança:

  • Item recorrente: cobra agora a proporção dos dias que faltam no ciclo (pró-rata). No cartão a cobrança é imediata; no Pix e no boleto é emitida com vencimento. O item passa a valer quando a pró-rata é paga.
  • Item único: cobra o valor cheio agora.
  • Sem pró-rata (prorata.enabled: false): nada é cobrado agora; o item entra a partir da próxima cobrança.
  • Pró-rata na próxima cobrança (prorata.mergeWithNextCycle: true): a proporção é somada à próxima cobrança.
  • Pix Automático: a pró-rata de item recorrente nunca gera Pix avulso; entra no próximo débito automático. Se o débito do próximo ciclo já foi enviado ao banco do pagador, o item só é cobrado a partir do ciclo seguinte, sem pró-rata (mode: AFTER_INSTRUCTED_CYCLE). Item único (ONE_TIME) continua cobrado na hora. Em autorização de valor fixo, adicionar item recorrente é recusado com PIX_AUTOMATICO_FIXED_AMOUNT.

Envie dryRun: true para ver os valores sem alterar nada.

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

subscriptions/write

Path Parameters

subscriptionIdstringobrigatório
ID da assinatura (ex: sub_xxx) - required

Body

application/json

Content-Type:application/json
JSON
{
    "priceId": "price_addon", 
    "quantity": 1, 
    "type": "RECURRING", 

    "prorata": { 
        "enabled": true, 
        "mergeWithNextCycle": false, 
        "dueDate": "2026-09-27" 
    },
    "boletoInstructions": { 
        "fine": 2.0, 
        "interest": 1.0 
    },
    "expirationAfterDueDate": 30, 
    "dryRun": false 

}

Schema

priceIdstringobrigatório
Plano do item que será adicionado
quantitynumberopcional
Quantidade (padrão 1)
typestringopcional
RECURRING: cobrado todo ciclo. ONE_TIME: cobrado uma vez (padrão RECURRING)
Valores aceitos:RECURRINGONE_TIME
prorataobjectopcional
Como cobrar a diferença dos dias restantes
boletoInstructionsobjectopcional
Multa, juros e desconto do boleto da pró-rata
expirationAfterDueDatenumberopcional
Dias depois do vencimento em que o boleto ou Pix ainda pode ser pago (0 a 60)
Regra:0 a 60
dryRunbooleanopcional
true: só simula e não altera nada
const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId/items';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "priceId": "price_addon", 
    "quantity": 1, 
    "type": "RECURRING", 

    "prorata": { 
        "enabled": true, 
        "mergeWithNextCycle": false, 
        "dueDate": "2026-09-27" 
    },
    "boletoInstructions": { 
        "fine": 2.0, 
        "interest": 1.0 
    },
    "expirationAfterDueDate": 30, 
    "dryRun": false 

})
};

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

Response Examples

200item adicionado▾
JSON
{
    "success": true, 
    "intent": "ADD", 
    "mode": "PRORATA_NOW", 
    "settlement": "AWAITING_PAYMENT", 
    "item": { 
        "itemId": "item_yyy", 
        "priceId": "price_yyy", 
        "quantity": 1, 
        "amount": 149.9, 
        "status": "PENDING_UPGRADE" 
    },
    "replacedItemId": null, 
    "adjustmentItemId": null, 
    "amounts": { 
        "delta": 50.0, 
        "prorata": 25.0, 
        "recurringTotal": 149.9, 
        "chargeTotal": 25.0 
    },
    "prorataPeriod": { 
        "startDate": "2026-09-24", 
        "endDate": "2026-10-09", 
        "days": 15, 
        "factor": 0.5, 
        "prorataAmount": 25.0 
    },
    "effectiveAt": "2026-10-10T00:00:00.000Z", 
    "invoiceId": "inv_yyy", 
    "charge": { 
        "chargeId": "cha_yyy", 
        "status": "AWAITING_PAYMENT", 
        "paymentType": "PIX", 
        "dueDate": "2026-09-27" 
    },
    "payment": { 
        "method": "PIX", 
        "pix": { 
            "emv": "00020126...", 
            "qrCode": "data:image/png;base64,iVBOR...", 
            "transactionId": "tx_xxx" 
        },
        "boleto": null, 
        "dueDate": "2026-09-27" 
    },
    "type": "DEFERRED_UPGRADE", 
    "chargeId": "cha_yyy", 
    "prorataAmount": 25.0, 
    "newAmount": 149.9, 
    "recurringTotal": 149.9, 
    "amount": 25.0, 
    "paymentMethod": "PIX", 
    "pix": { "emv": "00020126...", "qrCode": "data:image/png;base64,iVBOR...", "transactionId": "tx_xxx" }, 
    "dueDate": "2026-09-27" 
}

Campos da resposta

successboolean
true quando a alteração foi registrada
intentstring
ADD: item adicionado. REPLACE: item trocado
Valores aceitos:ADDREPLACE
modestring
Como a diferença de valor foi tratada
Valores aceitos:PRORATA_NOWNO_PRORATAPRORATA_NEXT_CYCLESCHEDULED_DOWNGRADERECURRENCE_CHANGEPENDING_REWRITEAFTER_INSTRUCTED_CYCLE
settlementstring
Situação da cobrança da diferença. PAID: paga no cartão. AWAITING_PAYMENT: Pix ou boleto emitido. NEXT_CYCLE_ENGINE: entra na próxima cobrança. CREDITED: virou crédito. RESCHEDULED: próxima cobrança remarcada. NONE: nada a cobrar
Valores aceitos:PAIDAWAITING_PAYMENTNONENEXT_CYCLE_ENGINEMERGED_INTO_OPEN_CHARGEMERGED_INTO_CHECKOUTCREDITEDRESCHEDULED
itemobject
Item criado ou alterado, no mesmo formato de items[] em Ver uma assinatura
replacedItemIdobject
Item substituído. Só na troca
adjustmentItemIdobject
Ajuste de pró-rata lançado na próxima cobrança
amountsobject
Valores da alteração, em reais
prorataPeriodobject
Dias considerados na pró-rata
effectiveAtstring
Quando o valor novo passa a valer nas cobranças
invoiceIdstring
Fatura da cobrança da diferença
chargeobject
Cobrança da diferença
paymentobject
Como pagar a cobrança da diferença
typestring
Resultado no formato antigo. Use mode e settlement
chargeIdstring
Use charge.chargeId
prorataAmountnumber
Use amounts.prorata
newAmountnumber
Valor novo do item. Use item.amount
recurringTotalnumber
Use amounts.recurringTotal
amountnumber
Use amounts.chargeTotal
paymentMethodstring
Use payment.method
Valores aceitos:pixcreditcardboletopix_automatico
pixobject
Use payment.pix
dueDatestring
Use charge.dueDate
Regra:^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
400pagamento recusado▾
JSON
{
    "error": {
        "message": "Cartão recusado por saldo insuficiente",
        "code": "PAYMENT_DECLINED",
        "details": { "declinedCode": "insufficient_funds" },
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Calcular pró-rata ou crédito

Próximo →

Trocar plano ou quantidade