Consultar

Listar assinaturas

Lista as assinaturas da conta, das mais recentes para as mais antigas, com filtros por situação, cliente, forma de pagamento, produto e período.

GET/v1/subscriptions

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

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

Paginação: a resposta traz pagination.lastKey. Para buscar a próxima página, repita a chamada enviando esse valor em lastKey. Quando lastKey vier null, não há mais páginas.

A assinatura nasce de uma cobrança recorrente criada em Cobranças (POST /v1/charges) ou de um link de pagamento. Esta rota não cria assinaturas.

Vendas avulsas (interval: ONE_TIME) não aparecem na lista.

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/read

Query Parameters

limitopcional

Quantidade de assinaturas por página (padrão 15)

lastKeyopcional

Cursor da próxima página, copiado de pagination.lastKey da resposta anterior

startDateopcional

Criadas a partir desta data. ISO 8601 recomendado (ex: 2026-03-10T00:00:00.000Z)

endDateopcional

Criadas até esta data. Use o fim do dia em ISO 8601 (ex: 2026-03-10T23:59:59.999Z)

statusopcional

Filtra por situação; aceita vários separados por vírgula: PENDING, TRIALING, ACTIVE, PAST_DUE, DEFAULT, EXPIRED, CANCELED, COMPLETED

searchopcional

Busca por nome ou documento do cliente, ou pelo ID da assinatura

documentopcional

CPF ou CNPJ do cliente

paymentMethodopcional

Forma de pagamento: CREDIT_CARD, PIX, BOLETO ou PIX_AUTOMATICO

priceIdopcional

ID do preço (plano)

productIdopcional

ID do produto

← Anterior

Remover Cliente

Ver uma assinatura

const url = 'https://sandbox.validapay.com.br/v1/subscriptions?limit=15';

const options = {
  method: 'GET',
  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

{
    "items": [ 
        {
            "subscriptionId": "sub_xxx", 
            "status": "ACTIVE", 
            "cancelAtPeriodEnd": false, 
            "productName": "Plano Pro - Mensal", 
            "paymentType": "CREDIT_CARD", 
            "interval": "MONTHLY", 
            "installments": 1, 
            "checkoutId": "pl_xxx", 
            "currentCycleNumber": 2, 
            "currentCycleAmount": 99.9, 
            "nextCycleAmount": 99.9, 
            "nextCycleChargeDate": "2026-11-10T00:00:00.000Z", 
            "createdAt": "2026-09-10T12:00:00.000Z", 
            "trialDays": 7, 
            "customer": { 
                "name": "João Silva", 
                "document": "12345678900" 
            },
            "lastCharge": { 
                "fees": { 
                    "total": 4.09, 
                    "payment": 4.09, 
                    "fixed": 0.12, 
                    "percentage": 3.97, 
                    "percentageRate": 3.97 
                },
                "netAmount": 95.81 
            }
        }
    ],
    "pagination": { 
        "totalPages": 3, 
        "lastKey": "eyJQSyI6..." 
    }
}

Campos da resposta

itemsarray[1]

Assinaturas da página

paginationobject

Paginação

← Anterior

Remover Cliente

Ver uma assinatura