Assinaturas

Adicionar Item

Adiciona um novo produto ou serviço a uma assinatura já existente.

Informe o priceId de um preço previamente cadastrado. Para assinaturas com cartão de crédito, a cobrança é processada imediatamente. Para PIX ou boleto, a resposta inclui payment.transactionId — a confirmação chega via webhook.

Pré-condições: assinatura ACTIVE ou PAST_DUE. Antes do 1º pagamento confirmado (currentCycleNumber === 1), add item retorna 400.

billOnNextCycle adia a cobrança para o próximo ciclo (apenas boleto/PIX; incompatível com cartão ou ONE_TIME).

Case de uso:

Como SaaS, quero adicionar um módulo extra (add-on) à assinatura de um cliente que já possui um plano base.

POST/v1/subscriptions/:subscriptionId/items

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

{
  "priceId": "price_xxx",
  "quantity": 1,
  "type": "RECURRING",
  "billOnNextCycle": false,
  "dueDate": "2026-04-06",
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0
  },
  "expirationAfterDueDate": 30
}

Schema

priceIdstringRequired

ID do preço do item

quantitynumberOptional

Quantidade (default 1, mínimo 1)

typestringOptional

RECURRING ou ONE_TIME (default RECURRING)

billOnNextCyclebooleanOptional

Adia cobrança para próximo ciclo (boleto/PIX apenas)

dueDatestringOptional

Regra:^\d{4}-\d{2}-\d{2}$

Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD)

boletoInstructionsobjectOptional

Para assinaturas com boleto

expirationAfterDueDatenumberOptional

Regra:0 a 60

Dias após vencimento (0 a 60, default 30)

← Anterior

Cancelar Assinatura

Atualizar Item

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_xxx",
  "quantity": 1,
  "type": "RECURRING",
  "billOnNextCycle": false,
  "dueDate": "2026-04-06",
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0
  },
  "expirationAfterDueDate": 30
})
};

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

Response Examples

200200 cartão

{
  "success": true,
  "type": "ADD_ITEM",
  "chargeId": "cha_xxx",
  "amount": 49.9,
  "newAmount": 149.8
}

200200 PIX

{
  "success": true,
  "type": "ADD_ITEM",
  "paymentMethod": "PIX",
  "chargeId": "cha_xxx",
  "payment": {
    "emvQrCode": "..."
  }
}

400400 pagamento

{
    "error": {
        "message": "Cartão recusado pela operadora",
        "code": "PAYMENT_DECLINED",
        "details": {
            "declinedCode": "card_declined"
        },
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

400400

{
    "error": {
        "message": "Assinatura não está ativa",
        "code": "SUBSCRIPTION_NOT_ACTIVE",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Cancelar Assinatura

Atualizar Item