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, 
    "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", 
                "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

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