Assinaturas

Listar Assinaturas

Lista todas as assinaturas da conta com suporte a filtros por status, cliente, método de pagamento, produto e período.

Utilize o campo lastKey retornado na resposta para navegar entre as páginas.

Status possíveis: PENDING, AWAITING_PAYMENT, ACTIVE, TRIALING, PAST_DUE, PAUSED, CANCELED, INCOMPLETE.

Assinaturas com interval: ONE_TIME são excluídas automaticamente do resultado.

Case de uso:

Como SaaS, quero listar todas as assinaturas ativas dos meus clientes para exibir no meu painel administrativo.

GET/v1/subscriptions

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

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

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 itens por página (default 15) - optional

lastKeyobrigatório

Cursor de paginação em base64 retornado na resposta anterior - optional

startDateobrigatório

Filtro por createdAt. ISO 8601 recomendado (ex: 2026-03-10T00:00:00.000Z). YYYY-MM-DD aceito - optional

endDateobrigatório

Filtro por createdAt. ISO 8601 com fim do dia (ex: 2026-03-10T23:59:59.999Z). YYYY-MM-DD pode excluir registros do mesmo dia com horário - optional

statusobrigatório

Filtro por status (lista separada por vírgula): PENDING, AWAITING_PAYMENT, ACTIVE, TRIALING, PAST_DUE, PAUSED, CANCELED, INCOMPLETE - optional

searchobrigatório

Busca por nome ou documento do cliente - optional

documentobrigatório

Filtro por CPF ou CNPJ do cliente - optional

paymentMethodobrigatório

Filtro por método: CREDIT_CARD, PIX, BOLETO ou PIX_AUTOMATICO. Alias aceito: paymentType - optional

priceIdobrigatório

Filtro por ID do preço - optional

productIdobrigatório

Filtro por ID do produto - optional

← Anterior

Remover Cliente

Buscar Assinatura

const url = 'https://sandbox.validapay.com.br/v1/subscriptions?limit=15&lastKey=&startDate=&endDate=&status=&search=&document=&paymentMethod=&priceId=&productId=?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

200200▾

JSON

{
  "items": [
    {
      "subscriptionId": "sub_xxx",
      "status": "ACTIVE",
      "interval": "MONTHLY",
      "billingDay": 15,
      "currentCycleNumber": 3,
      "currentCycleAmount": 99.9,
      "nextCycleChargeDate": "2024-02-15",
      "customer": {
        "customerId": "cus_xxx",
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "lastCharge": {
        "netAmount": 98.91,
        "status": "PAID"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "hasMore": true,
    "lastKey": "eyJ..."
  }
}

← Anterior

Remover Cliente

Buscar Assinatura