# Ver uma assinatura

**Área:** Consultar

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`

**Scopes necessários:** `subscriptions/read`

**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.

### Path parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `subscriptionId` | **sim** | ID da assinatura (ex: sub_xxx) - required |

### Resposta 200: 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

| Campo | Descrição |
|---|---|
| `subscriptionId` | ID da assinatura |
| `customerId` | ID do cliente |
| `status` | Situação da assinatura (valores: PENDING, TRIALING, ACTIVE, PAST_DUE, DEFAULT, EXPIRED, CANCELED, COMPLETED) |
| `interval` | Periodicidade da cobrança (valores: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY) |
| `billingDay` | Dia do mês em que a cobrança vence |
| `paymentType` | Forma de pagamento (valores: CREDIT_CARD, PIX, BOLETO, PIX_AUTOMATICO) |
| `allowedPaymentMethods` | Formas de pagamento que o cliente pode escolher na fatura |
| `passFeesToCustomer` | true quando as taxas do cartão são repassadas ao cliente |
| `productId` | ID do produto |
| `priceId` | ID do plano principal |
| `checkoutId` | Link de pagamento que originou a assinatura |
| `checkoutUrl` | Link para o cliente concluir o primeiro pagamento. Só vem enquanto ele não pagou |
| `name` | Nome do cliente gravado na assinatura |
| `email` | E-mail do cliente gravado na assinatura |
| `document` | CPF ou CNPJ gravado na assinatura |
| `taxId` | CPF ou CNPJ gravado na assinatura (mesmo valor de document) |
| `additionalEmails` | E-mails que recebem cópia das notificações |
| `currentCycleNumber` | Número da cobrança atual |
| `currentCycleAmount` | Valor da cobrança atual, em reais |
| `nextCycleAmount` | Valor previsto para a próxima cobrança, em reais |
| `nextCycleChargeDate` | Data da próxima cobrança |
| `cancelAtPeriodEnd` | true quando o cancelamento acontece no fim do período pago |
| `splitRules` | Divisão do valor com outras contas (split) |
| `boletoInstructions` | Multa, juros e desconto aplicados aos boletos |
| `pixInstructions` | Multa, juros e desconto aplicados ao Pix com vencimento |
| `issueDaysBeforeDue` | Quantos dias antes do vencimento o boleto ou Pix é emitido |
| `expirationAfterDueDate` | Quantos dias depois do vencimento a cobrança ainda pode ser paga |
| `allowConcurrentCycles` | "true" quando um ciclo novo pode ser cobrado com outro ainda em aberto |
| `nfConfigId` | Configuração de nota fiscal usada nas cobranças |
| `createdAt` | Data de criação |
| `updatedAt` | Data da última alteração |
| `notificationEmails` | Para quem vão os e-mails da assinatura |
| `notificationEmails.primary` | E-mail principal |
| `notificationEmails.additional` | E-mails em cópia |
| `primaryItemId` | Item que representa o plano principal |
| `cancellation` | Como seria um cancelamento feito agora |
| `cancellation.immediate` | true: cancela na hora. false: cancela no fim do período já pago |
| `cancellation.effectiveAt` | Quando o cancelamento passaria a valer |
| `card` | Cartão usado nas cobranças. null quando a forma de pagamento não é cartão |
| `card.brand` | Bandeira |
| `card.firstSix` | 6 primeiros dígitos |
| `card.lastFour` | 4 últimos dígitos |
| `customer` | Dados atuais do cadastro do cliente |
| `customer.customerId` | ID do cliente |
| `customer.name` | Nome |
| `customer.email` | E-mail |
| `customer.phone` | Telefone |
| `customer.document` | CPF ou CNPJ |
| `customer.ltv` | Total já pago pelo cliente, em reais |
| `customer.additionalEmails` | E-mails em cópia do cadastro |
| `customerAddress` | Endereço do cliente |
| `customerAddress.street` | Logradouro |
| `customerAddress.number` | Número |
| `customerAddress.complement` | Complemento |
| `customerAddress.neighborhood` | Bairro |
| `customerAddress.city` | Cidade |
| `customerAddress.state` | UF |
| `customerAddress.zipCode` | CEP |
| `coupon` | Cupom aplicado à assinatura |
| `coupon.code` | Código do cupom |
| `coupon.discountType` | Tipo de benefício (valores: PERCENTAGE, FIXED, EXTRA_PERIOD) |
| `coupon.discountValue` | Percentual, valor em reais ou quantidade de períodos grátis, conforme o tipo |
| `coupon.extraPeriodUnit` | Unidade do período grátis, só em EXTRA_PERIOD (valores: DAYS, MONTHS) |
| `items` | Itens da assinatura (plano principal e adicionais) |
| `items.itemId` | ID do item |
| `items.name` | Nome do item |
| `items.amount` | Valor unitário, em reais |
| `items.quantity` | Quantidade |
| `items.discount` | Desconto do item, em reais |
| `items.type` | RECURRING: cobrado todo ciclo. ONE_TIME: cobrado uma vez (valores: RECURRING, ONE_TIME) |
| `items.status` | Situação do item (valores: ACTIVE, PENDING, PENDING_UPGRADE, AWAITING_PAYMENT, TRIALING, CHARGED, CANCELED) |
| `items.origin` | Origem do item; PRORATA_ADJUSTMENT indica ajuste de pró-rata |
| `items.priceId` | ID do plano |
| `items.productId` | ID do produto |
| `items.createdAt` | Data de inclusão |
| `items.upgradedFromItemId` | Item que este substituiu numa troca de plano |
| `items.upgradedToItemId` | Item que substituiu este numa troca de plano |
| `items.price` | Plano do item |
| `items.price.title` | Nome do plano |
| `items.price.amount` | Valor do plano, em reais |
| `items.price.statementDescriptor` | Nome que aparece na fatura do cartão |
| `items.price.recurrenceType` | Periodicidade do plano (valores: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY, ONE_TIME) |
| `items.price.recurrenceInterval` | A cada quantos períodos cobra (1 = todo mês, se mensal) |
| `items.price.productId` | ID do produto |
| `items.product` | Produto do item |
| `items.product.name` | Nome do produto |
| `items.product.type` | Tipo do produto |
| `billingCycles` | Histórico de cobranças, um registro por ciclo |
| `billingCycles.cycleNumber` | Número do ciclo |
| `billingCycles.cycle` | Situação do ciclo |
| `billingCycles.cycle.status` | Situação do ciclo (valores: SCHEDULED, PENDING, AWAITING_PAYMENT, PROCESSING, RETRY_SCHEDULED, DUNNING, PAID, FAILED, EXPIRED, CANCELED) |
| `billingCycles.cycle.amount` | Valor do ciclo, em reais |
| `billingCycles.cycle.chargeDate` | Data de vencimento do ciclo |
| `billingCycles.cycle.chargeId` | Cobrança que pagou ou vai pagar o ciclo |
| `billingCycles.cycle.paymentMethod` | Forma de pagamento do ciclo |
| `billingCycles.cycle.discount` | Desconto manual aplicado ao ciclo |
| `billingCycles.cycle.splitRules` | Split aplicado ao ciclo |
| `billingCycles.cycle.rulerHistory` | Mensagens da régua de cobrança já enviadas |
| `billingCycles.cycle.manualRetryCount` | Quantas vezes a cobrança foi retentada pelo painel |
| `billingCycles.cycle.lastManualRetryAt` | Última retentativa pelo painel |
| `billingCycles.cycle.pixAutoScheduledEndToEndId` | Identificador do agendamento no Pix Automático |
| `billingCycles.credit` | Crédito de troca de plano que abate este ciclo |
| `billingCycles.expectedIssueDate` | Quando a cobrança do ciclo será emitida. Só vem em ciclo ainda não emitido |
| `billingCycles.invoices` | Faturas do ciclo |
| `billingCycles.invoices.invoiceId` | ID da fatura |
| `billingCycles.invoices.invoiceNumber` | Número da fatura |
| `billingCycles.invoices.status` | Situação da fatura (valores: PENDING, AWAITING_PAYMENT, OVERDUE, PAID, CANCELED, EXPIRED, UNCOLLECTIBLE) |
| `billingCycles.invoices.paymentType` | Forma de pagamento da fatura |
| `billingCycles.invoices.dueDate` | Vencimento |
| `billingCycles.invoices.paidAt` | Data do pagamento |
| `billingCycles.invoices.canceledAt` | Data do cancelamento da fatura |
| `billingCycles.invoices.discount` | Desconto manual da fatura |
| `billingCycles.invoices.summary` | Totais da fatura |
| `billingCycles.invoices.summary.discount` | Desconto, em reais |
| `billingCycles.invoices.summary.total` | Total, em reais |
| `billingCycles.invoices.lineItems` | Linhas da fatura |
| `billingCycles.invoices.lineItems.name` | Descrição da linha |
| `billingCycles.invoices.lineItems.productName` | Produto |
| `billingCycles.invoices.lineItems.planName` | Plano |
| `billingCycles.invoices.lineItems.type` | Tipo da linha (RECURRING, ONE_TIME, PRORATA_UPGRADE...) |
| `billingCycles.invoices.lineItems.origin` | Origem da linha |
| `billingCycles.invoices.lineItems.netAmount` | Valor da linha, em reais |
| `billingCycles.invoices.lineItems.quantity` | Quantidade |
| `billingCycles.invoices.lineItems.priceId` | ID do plano |
| `billingCycles.invoices.lineItems.productId` | ID do produto |
| `billingCycles.invoices.charge` | Cobrança desta fatura |
| `billingCycles.invoices.charge.chargeId` | ID da cobrança |
| `billingCycles.invoices.charge.paymentType` | Forma de pagamento |
| `billingCycles.invoices.charge.payer` | Quem pagou (Pix): nome e documento |
| `billingCycles.invoices.charge.manualSettlement` | Baixa manual feita pelo painel: forma e observação |
| `billingCycles.charge` | Cobrança principal do ciclo |
| `billingCycles.charge.type` | Tipo da cobrança |
| `billingCycles.charge.paymentType` | Forma de pagamento |
| `billingCycles.charge.amount` | Valor cobrado, em reais |
| `billingCycles.charge.grossAmount` | Valor bruto, em reais |
| `billingCycles.charge.netAmount` | Valor que você recebe, em reais |
| `billingCycles.charge.fees` | Taxas |
| `billingCycles.charge.fees.total` | Total de taxas, em reais |
| `billingCycles.charge.fees.fixed` | Parte fixa, em reais |
| `billingCycles.charge.fees.percentageRate` | Percentual aplicado |
| `billingCycles.charge.paidAt` | Data do pagamento |
| `billingCycles.charge.createdAt` | Data de criação da cobrança |
| `planChanges` | Histórico de trocas de plano |
| `paymentMethodChanges` | Histórico de trocas de forma de pagamento |
| `dueDateChanges` | Histórico de trocas de dia de vencimento |

### Resposta 404: 404

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


---

Página: https://docs.validapay.com.br/referencia/get-ver-uma-assinatura  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json