Consultar

Ver uma assinatura

Mostra tudo sobre uma assinatura: plano e itens, cliente, cartão, cupom, histórico de cobranças (ciclos, faturas e pagamentos) e as trocas de plano, forma de pagamento e vencimento.

GET/v1/subscriptions/:subscriptionId

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

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

Ciclo é cada período cobrado da assinatura (1ª mensalidade, 2ª mensalidade...). Cada ciclo tem uma ou mais faturas, e cada fatura tem a cobrança que o cliente paga.

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

Path Parameters

subscriptionIdstringobrigatório

ID da assinatura (ex: sub_xxx) - required

← Anterior

Listar assinaturas

Calcular pró-rata ou crédito

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

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

{
    "subscriptionId": "sub_xxx", 
    "customerId": "cus_xxx", 
    "status": "ACTIVE", 
    "interval": "MONTHLY", 
    "billingDay": 10, 
    "paymentType": "CREDIT_CARD", 
    "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
    "passFeesToCustomer": false, 
    "productId": "prod_xxx", 
    "priceId": "price_xxx", 
    "checkoutId": "pl_xxx", 
    "checkoutUrl": null, 
    "name": "João Silva", 
    "email": "joao@email.com", 
    "document": "12345678900", 
    "taxId": "12345678900", 
    "additionalEmails": [], 
    "currentCycleNumber": 2, 
    "currentCycleAmount": 99.9, 
    "nextCycleAmount": 99.9, 
    "nextCycleChargeDate": "2026-11-10T00:00:00.000Z", 
    "cancelAtPeriodEnd": false, 
    "splitRules": [], 
    "boletoInstructions": null, 
    "pixInstructions": null, 
    "issueDaysBeforeDue": 10, 
    "expirationAfterDueDate": 30, 
    "allowConcurrentCycles": null, 
    "nfConfigId": null, 
    "discountSchedule": null, 
    "createdAt": "2026-09-10T12:00:00.000Z", 
    "updatedAt": "2026-10-10T12:00:00.000Z", 
    "notificationEmails": { 
        "primary": "joao@email.com", 
        "additional": [] 
    },
    "primaryItemId": "item_xxx", 
    "cancellation": { 
        "immediate": false, 
        "effectiveAt": "2026-11-10T00:00:00.000Z" 
    },
    "card": { 
        "brand": "VISA", 
        "firstSix": "411111", 
        "lastFour": "1111" 
    },
    "customer": { 
        "customerId": "cus_xxx", 
        "name": "João Silva", 
        "email": "joao@email.com", 
        "phone": "11999998888", 
        "document": "12345678900", 
        "ltv": 199.8, 
        "additionalEmails": [] 
    },
    "customerAddress": { 
        "street": "Rua Exemplo", 
        "number": "100", 
        "complement": null, 
        "neighborhood": "Centro", 
        "city": "Campinas", 
        "state": "SP", 
        "zipCode": "13010000" 
    },
    "coupon": { 
        "code": "BEMVINDO", 
        "discountType": "PERCENTAGE", 
        "discountValue": 10, 
        "extraPeriodUnit": null 
    },
    "items": [ 
        {
            "itemId": "item_xxx", 
            "name": "Plano Pro - Mensal", 
            "amount": 99.9, 
            "quantity": 1, 
            "discount": 0, 
            "type": "RECURRING", 
            "status": "ACTIVE", 
            "origin": null, 
            "priceId": "price_xxx", 
            "productId": "prod_xxx", 
            "createdAt": "2026-09-10T12:00:00.000Z", 
            "upgradedFromItemId": null, 
            "upgradedToItemId": null, 
            "price": { 
                "title": "Mensal", 
                "amount": 99.9, 
                "statementDescriptor": "VALIDAPAY", 
                "recurrenceType": "MONTHLY", 
                "recurrenceInterval": 1, 
                "productId": "prod_xxx" 
            },
            "product": { 
                "name": "Plano Pro", 
                "type": "RECURRING" 
            }
        }
    ],
    "billingCycles": [ 
        {
            "cycleNumber": 2, 
            "cycle": { 
                "status": "PAID", 
                "amount": 99.9, 
                "chargeDate": "2026-10-10T00:00:00.000Z", 
                "chargeId": "cha_xxx", 
                "invoiceId": "inv_xxx", 
                "paymentMethod": "creditcard", 
                "discount": null, 
                "splitRules": [], 
                "rulerHistory": [], 
                "manualRetryCount": 0, 
                "lastManualRetryAt": null, 
                "pixAutoScheduledEndToEndId": null 
            },
            "credit": null, 
            "expectedIssueDate": null, 
            "invoices": [ 
                {
                    "invoiceId": "inv_xxx", 
                    "invoiceNumber": "000002", 
                    "status": "PAID", 
                    "paymentType": "CREDIT_CARD", 
                    "dueDate": "2026-10-10T00:00:00.000Z", 
                    "paidAt": "2026-10-10T12:00:00.000Z", 
                    "canceledAt": null, 
                    "discount": null, 
                    "summary": { 
                        "discount": 0, 
                        "total": 99.9 
                    },
                    "lineItems": [ 
                        {
                            "name": "Plano Pro - Mensal", 
                            "productName": "Plano Pro", 
                            "planName": "Mensal", 
                            "type": "RECURRING", 
                            "origin": null, 
                            "netAmount": 99.9, 
                            "quantity": 1, 
                            "priceId": "price_xxx", 
                            "productId": "prod_xxx" 
                        }
                    ],
                    "charge": { 
                        "chargeId": "cha_xxx", 
                        "paymentType": "CREDIT_CARD", 
                        "payer": null, 
                        "manualSettlement": null 
                    }
                }
            ],
            "charge": { 
                "type": "RECURRING", 
                "paymentType": "CREDIT_CARD", 
                "amount": 99.9, 
                "grossAmount": 99.9, 
                "netAmount": 95.81, 
                "fees": { 
                    "total": 4.09, 
                    "fixed": 0.12, 
                    "percentageRate": 3.97 
                },
                "paidAt": "2026-10-10T12:00:00.000Z", 
                "createdAt": "2026-10-10T11:59:58.000Z" 
            }
        }
    ],
    "planChanges": [], 
    "paymentMethodChanges": [], 
    "dueDateChanges": [] 
}

Campos da resposta

subscriptionIdstring

ID da assinatura

customerIdstring

ID do cliente

statusstring

Situação da assinatura

Valores aceitos:PENDINGTRIALINGACTIVEPAST_DUEDEFAULTEXPIREDCANCELEDCOMPLETED

intervalstring

Periodicidade da cobrança

Valores aceitos:DAILYWEEKLYMONTHLYQUARTERLYSEMIANNUALYEARLY

billingDaynumber

Dia do mês em que a cobrança vence

Regra:1 a 31

paymentTypestring

Forma de pagamento

Valores aceitos:CREDIT_CARDPIXBOLETOPIX_AUTOMATICO

allowedPaymentMethodsarray[3]

Formas de pagamento que o cliente pode escolher na fatura

Valores aceitos:pixcreditcardboletopix_automatico

passFeesToCustomerboolean

true quando as taxas do cartão são repassadas ao cliente

productIdstring

ID do produto

Regra:^prod_

priceIdstring

ID do plano principal

checkoutIdstring

Link de pagamento que originou a assinatura

checkoutUrlobject

Link para o cliente concluir o primeiro pagamento. Só vem enquanto ele não pagou

namestring

Nome do cliente gravado na assinatura

emailstring

E-mail do cliente gravado na assinatura

Regra:email

documentstring

CPF ou CNPJ gravado na assinatura

Regra:^(\d{11}|\d{14})$

taxIdstring

CPF ou CNPJ gravado na assinatura (mesmo valor de document)

additionalEmailsarray[0]

E-mails que recebem cópia das notificações

Regra:email

currentCycleNumbernumber

Número da cobrança atual

currentCycleAmountnumber

Valor da cobrança atual, em reais

nextCycleAmountnumber

Valor previsto para a próxima cobrança, em reais

nextCycleChargeDatestring

Data da próxima cobrança

cancelAtPeriodEndboolean

true quando o cancelamento acontece no fim do período pago

splitRulesarray[0]

Divisão do valor com outras contas (split)

boletoInstructionsobject

Multa, juros e desconto aplicados aos boletos

pixInstructionsobject

Multa, juros e desconto aplicados ao Pix com vencimento

issueDaysBeforeDuenumber

Quantos dias antes do vencimento o boleto ou Pix é emitido

expirationAfterDueDatenumber

Quantos dias depois do vencimento a cobrança ainda pode ser paga

Regra:0 a 60

allowConcurrentCyclesobject

"true" quando um ciclo novo pode ser cobrado com outro ainda em aberto

nfConfigIdobject

Configuração de nota fiscal usada nas cobranças

discountScheduleobject

Desconto recorrente da assinatura: type, value, startCycleNumber, cycles, lastCycleNumber e endedAt. Ver Aplicar desconto em uma cobrança

createdAtstring

Data de criação

updatedAtstring

Data da última alteração

notificationEmailsobject

Para quem vão os e-mails da assinatura

primaryItemIdstring

Item que representa o plano principal

cancellationobject

Como seria um cancelamento feito agora

cardobject

Cartão usado nas cobranças. null quando a forma de pagamento não é cartão

customerobject

Dados atuais do cadastro do cliente

customerAddressobject

Endereço do cliente

couponobject

Cupom aplicado à assinatura

itemsarray[1]

Itens da assinatura (plano principal e adicionais)

billingCyclesarray[1]

Histórico de cobranças, um registro por ciclo

planChangesarray[0]

Histórico de trocas de plano

paymentMethodChangesarray[0]

Histórico de trocas de forma de pagamento

dueDateChangesarray[0]

Histórico de trocas de dia de vencimento

404▾

JSON

{
    "error": {
        "message": "Assinatura não encontrada",
        "code": "SUBSCRIPTION_NOT_FOUND",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Listar assinaturas

Calcular pró-rata ou crédito