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.

Pix Automático:

Se o débito do próximo ciclo já foi enviado ao banco do pagador, ele sai com o valor atual e a remoção vale a partir do ciclo seguinte. A resposta traz instructedCycle, effectiveCycleNumber, e effectiveDate com a data desse ciclo.
Remoção que deixe a mensalidade abaixo do mínimo do Pix Automático é recusada com PIX_AUTOMATICO_MIN_AMOUNT; em autorização de valor fixo, com PIX_AUTOMATICO_FIXED_AMOUNT.

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

200Pix Automático com débito já enviado▾

JSON

{
    "success": true,
    "type": "ITEM_REMOVED",
    "subscriptionId": "sub_xxx",
    "itemId": "item_addon",
    "removedAmount": 30.0,
    "recurringTotal": 99.9,
    "effectiveAt": "NEXT_CYCLE",
    "effectiveDate": "2026-11-10T00:00:00.000Z", 
    "instructedCycle": { 
        "cycleNumber": 4, 
        "chargeDate": "2026-10-10T00:00:00.000Z", 
        "amount": 129.9 
    },
    "effectiveCycleNumber": 5 
}

Campos da resposta

successboolean

typestring

subscriptionIdstring

itemIdstring

removedAmountnumber

recurringTotalnumber

effectiveAtstring

effectiveDatestring

Vencimento do ciclo seguinte ao débito já enviado

instructedCycleobject

Débito Pix Automático já enviado ao banco do pagador, que mantém o valor com o item. Só quando existe

effectiveCycleNumbernumber

Primeiro ciclo cobrado sem o item. Só quando existe débito já enviado

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