Plano e itens

Remover item

Remove um item da assinatura.

DELETE/v1/subscriptions/:subscriptionId/items/:itemId

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

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

O que acontece com a cobrança: por padrão o item sai a partir da próxima cobrança, e a cobrança atual não muda. Com effectiveAt: "IMMEDIATE", o item sai já do ciclo atual.

O plano principal não pode ser removido; para encerrar a assinatura use Cancelar assinatura.

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

itemIdstringobrigatório

ID do item da assinatura, em items[].itemId de Ver uma assinatura (ex: item_xxx) - required

Body

application/json

Content-Type:application/json

JSON

{
    "effectiveAt": "NEXT_CYCLE" 
}

Schema

effectiveAtstringopcional

NEXT_CYCLE: sai a partir da próxima cobrança. IMMEDIATE: sai já do ciclo atual (padrão NEXT_CYCLE)

Valores aceitos:NEXT_CYCLEIMMEDIATE

← Anterior

Trocar plano ou quantidade

Trocar cartão ou método de pagamento

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

const options = {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

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

Response Examples

200▾

JSON

{
    "success": true, 
    "type": "ITEM_REMOVED", 
    "subscriptionId": "sub_xxx", 
    "itemId": "item_addon", 
    "removedAmount": 30.0, 
    "recurringTotal": 99.9, 
    "effectiveAt": "NEXT_CYCLE", 
    "effectiveDate": "2026-10-10T00:00:00.000Z" 
}

Campos da resposta

successboolean

true quando o item foi removido

typestring

ITEM_REMOVED: removido agora. ALREADY_REMOVED: o item já tinha sido removido

Valores aceitos:ITEM_REMOVEDALREADY_REMOVED

subscriptionIdstring

ID da assinatura

itemIdstring

Item removido

removedAmountnumber

Quanto o item representava por ciclo, em reais

recurringTotalnumber

Novo total recorrente da assinatura, em reais

effectiveAtstring

Quando a remoção vale

Valores aceitos:NEXT_CYCLEIMMEDIATE

effectiveDatestring

Data a partir da qual o item deixa de ser cobrado

404▾

JSON

{
    "error": {
        "message": "Item não encontrado",
        "code": "ITEM_NOT_FOUND",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Trocar plano ou quantidade

Trocar cartão ou método de pagamento