> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Buscar assinatura por ID
> Retorna a assinatura com os itens que ela cobra.
`GET /subscriptions/:id`
Faz parte do recurso [Assinaturas](/pt-BR/subscriptions) — o conceito e os dez estados estão lá.
Devolve a assinatura completa: o estado, as datas do ciclo, a forma de pagamento padrão e os
`items` — o que ela cobra, cada um com `name`, `unitAmount` e `quantity`. Não existe rota separada
para os itens.
**Os itens são um retrato do que foi contratado, não do catálogo.** Cada um guarda o
`priceVersionId` que valia na contratação, e é por ele que a cobrança continua acontecendo mesmo
depois de o plano ser reajustado ou o item ser arquivado. Ver
[Criar versão de preço](/pt-BR/subscriptions/plans/prices-post).
**`nextInvoiceAt` é a data da próxima emissão, não da próxima cobrança.** Boleto e PIX são
registrados com alguns dias de antecedência do vencimento, então a fatura nasce antes da data em
que o dinheiro entra. Ver [Ciclos](/pt-BR/subscriptions/ciclos).
**Em `trialing`, `currentPeriodEnd` é o fim do teste.** O período corrente de uma assinatura em
teste **é** o teste, e o ciclo recorrente só começa a contar quando ele acaba — por isso
`nextInvoiceAt` aponta para o fim do teste, e não para daqui a um mês.
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "sub_x33m4yn6brazh71en4mki6f5c",
"number": { "sequence": 42 },
"referenceCode": "contrato-2026-0042",
"customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
"customerName": "Ana Souza",
"status": "active",
"currency": "BRL",
"collectionMethod": "charge_automatically",
"collectionTiming": "prepaid",
"invoiceGenerationMode": "just_in_time",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"cancelAtPeriodEnd": false,
"canceledAt": null,
"pausedAt": null,
"trialEnd": null,
"maxCycles": null,
"issuedCycles": 1,
"completedCycles": 1,
"currentPeriodStart": "2026-08-10T12:00:00.000Z",
"currentPeriodEnd": "2026-09-10T12:00:00.000Z",
"nextInvoiceAt": "2026-09-10T12:00:00.000Z",
"latestInvoiceId": "inv_p9c4zjm1x6bnvea075rkftusd",
"items": [
{
"id": "subi_wq3n8fk52hbdzr7m0aeypvcjt",
"subscriptionId": "sub_x33m4yn6brazh71en4mki6f5c",
"planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"priceVersionId": "price_l1r8693wk6ksbd9044bwvwu93",
"name": "Assinatura Pro",
"unitAmount": 9900,
"quantity": 1,
"addedAt": "2026-08-10T12:00:00.000Z",
"removedAt": null
}
]
}
```
O exemplo está abreviado — o playground ao lado mostra o corpo inteiro.
## OpenAPI
````yaml openapi/billing.json GET /subscriptions/{id}
openapi: 3.0.3
info:
title: Z2Pay Billing API
version: 1.0.0
description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Invoices
description: Faturas emitidas pelas assinaturas
- name: Plans
description: Planos de cobrança e versões de preço
- name: Subscriptions
description: Assinaturas recorrentes
paths:
/subscriptions/{id}:
get:
tags:
- Subscriptions
summary: Buscar assinatura por ID
description: >-
Retorna a assinatura com os itens que ela cobra. Cada item traz `name` —
o que se cobra.
operationId: SubscriptionController_getById
parameters:
- name: id
in: path
required: true
description: ID da assinatura
schema:
type: string
responses:
'200':
description: Assinatura com seus itens
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
number:
type: object
properties:
sequence:
type: integer
description: >-
Número sequencial do documento dentro da numeração
(assinatura ou fatura).
description: Número do endereço.
referenceCode:
type: string
description: >-
Código do contrato no sistema do integrador; pesquisável,
sem unicidade.
nullable: true
customerId:
type: string
description: ID do cliente associado ao registro.
customerEmail:
type: string
description: E-mail do cliente.
customerName:
type: string
description: Nome do cliente.
customerDocument:
type: string
description: Documento do cliente (CPF ou CNPJ).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
status:
type: string
enum:
- incomplete
- incomplete_expired
- trialing
- active
- past_due
- unpaid
- paused
- canceled
- completed
description: >-
Status atual do registro (assinatura, fatura, plano ou
slip de pagamento).
billingGroupId:
nullable: true
description: >-
ID do grupo de cobrança ao qual o registro pertence; nulo
se não agrupado.
currentPeriodStart:
type: string
format: date-time
description: >-
Início do período de cobrança atual da assinatura (ISO
8601).
currentPeriodEnd:
type: string
format: date-time
description: Fim do período de cobrança atual da assinatura (ISO 8601).
nextInvoiceAt:
type: string
format: date-time
description: >-
Data e hora prevista para a próxima fatura da assinatura
(ISO 8601).
nullable: true
recurrence:
type: object
properties:
interval:
type: integer
description: >-
Quantidade de unidades por ciclo de cobrança (ex.:
interval 3 + unit month = trimestral).
unit:
type: string
description: >-
Unidade do ciclo de cobrança: day, week, month ou
year.
anchor:
type: string
description: >-
Âncora que fixa a data de renovação do ciclo:
subscription_start, day_of_month ou end_of_month.
anchorDay:
type: integer
description: >-
Dia do mês (1–31) usado quando a âncora é
day_of_month.
collectionTiming:
type: string
description: >-
Momento da cobrança do ciclo: prepaid (no início) ou
postpaid (no fim).
description: >-
Regra de recorrência (intervalo, unidade e âncora do
ciclo).
collectionMethod:
type: string
enum:
- charge_automatically
description: >-
Como a fatura é cobrada. Hoje só a cobrança automática na
forma de pagamento padrão.
collectionTiming:
type: string
enum:
- prepaid
- postpaid
description: >-
Momento da cobrança do ciclo: prepaid (no início) ou
postpaid (no fim).
invoiceGenerationMode:
type: string
enum:
- just_in_time
- upfront
description: >-
Modo de geração de faturas: just_in_time (a cada ciclo) ou
upfront (todas antecipadas).
cancelAtPeriodEnd:
type: boolean
description: >-
Indica se a assinatura será cancelada ao fim do período
atual.
canceledAt:
nullable: true
description: >-
Data e hora do cancelamento; nula se não cancelado (ISO
8601).
endedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi efetivamente
encerrada; nula se ainda ativa (ISO 8601).
cancellationReason:
nullable: true
description: Motivo do cancelamento da assinatura.
pausedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi pausada; nula se não
pausada (ISO 8601).
pauseResumesAt:
nullable: true
description: >-
Data e hora agendada para a retomada automática da
assinatura pausada (ISO 8601).
pauseReason:
nullable: true
description: Motivo da pausa da assinatura.
trialEnd:
nullable: true
description: >-
Data e hora de término do período de teste; nula se sem
trial (ISO 8601).
incompleteExpiresAt:
nullable: true
description: >-
Prazo para concluir o primeiro pagamento antes de a
assinatura incompleta expirar (ISO 8601).
trialRemindersFired:
type: array
items: {}
description: >-
Lembretes de fim do período de teste já disparados para a
assinatura.
maxCycles:
type: integer
description: >-
Número máximo de ciclos da assinatura; nulo se não houver
limite.
nullable: true
issuedCycles:
type: integer
description: >-
Número de ciclos já faturados (faturas emitidas) da
assinatura.
completedCycles:
type: integer
description: Número de ciclos já concluídos (pagos) da assinatura.
defaultPaymentMethodRef:
type: object
properties:
id:
type: string
description: Identificador único do registro.
nullable: true
type:
type: string
description: >-
Tipo da referência: meio da forma de pagamento (card,
pix, boleto) ou natureza da linha da fatura.
description: >-
Referência da forma de pagamento padrão usada para cobrar
a assinatura.
splitConfig:
nullable: true
description: >-
Configuração de divisão (split) dos valores entre
recebedores; nula se sem split.
paymentBehavior:
type: string
enum:
- allow_incomplete
- error_if_incomplete
description: >-
O que fazer quando a primeira cobrança não é aprovada:
allow_incomplete cria a assinatura com a fatura em aberto;
error_if_incomplete cancela a assinatura.
latestInvoiceId:
type: string
description: ID da fatura mais recente gerada pela assinatura.
paymentUpdateToken:
nullable: true
description: >-
Token do link público para o cliente atualizar a forma de
pagamento; nulo se não gerado.
paymentUpdateMethods:
nullable: true
description: >-
Formas de pagamento permitidas no link público de troca;
nula se não habilitada.
metadata:
type: object
properties: {}
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
items:
type: array
description: Itens que a assinatura cobra.
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
subscriptionId:
type: string
description: ID da assinatura relacionada ao registro.
planItemId:
type: string
description: >-
ID do componente (plan item) ao qual o preço se
refere.
nullable: true
priceVersionId:
type: string
description: ID da versão de preço aplicada ao item.
nullable: true
name:
type: string
nullable: true
description: >-
O que se cobra. Vem do item do plano, ou da
descrição do item avulso.
unitAmount:
type: integer
description: Valor unitário do item, em centavos.
quantity:
type: integer
description: Quantidade do item.
addedAt:
type: string
format: date-time
description: >-
Data e hora em que o item foi adicionado à
assinatura (ISO 8601).
removedAt:
nullable: true
description: >-
Data e hora em que o item foi removido da
assinatura; nula se ainda ativo (ISO 8601).
example:
id: sub_hsm2kigu74htdxj3nw2z6f9xw
number:
sequence: 42
referenceCode: CONTRATO-2026-0042
customerId: cust_c72q6ogr9iko0we85mqal04te
customerEmail: maria.silva@example.com
customerName: Maria Silva
customerDocument: '12345678909'
currency: BRL
status: active
billingGroupId: null
currentPeriodStart: '2025-06-01T03:00:00.000Z'
currentPeriodEnd: '2025-07-01T03:00:00.000Z'
nextInvoiceAt: '2025-07-01T03:00:00.000Z'
recurrence:
interval: 1
unit: month
anchor: day_of_month
anchorDay: 1
collectionTiming: prepaid
collectionMethod: charge_automatically
collectionTiming: prepaid
invoiceGenerationMode: just_in_time
cancelAtPeriodEnd: false
canceledAt: null
endedAt: null
cancellationReason: null
pausedAt: null
pauseResumesAt: null
pauseReason: null
trialEnd: null
incompleteExpiresAt: null
trialRemindersFired: []
maxCycles: 12
issuedCycles: 1
completedCycles: 1
defaultPaymentMethodRef:
id: crd_tsj66oabsygc9kwvvzt8189f9
type: card
splitConfig: null
paymentBehavior: allow_incomplete
latestInvoiceId: inv_c3qahi4qnkc258lfc14gplupt
paymentUpdateToken: null
paymentUpdateMethods: null
metadata: {}
createdAt: '2025-06-01T13:45:30.000Z'
updatedAt: '2025-06-01T13:45:30.000Z'
items:
- id: subi_k9m3xqr7wt2zpf5hnc8ydv4bj
subscriptionId: sub_hsm2kigu74htdxj3nw2z6f9xw
planItemId: pli_hqx9z6jinrx1arv96nb5xus4p
priceVersionId: price_t4wz8hqm2xkcr9pfs5ynd3vbj
name: Assinatura base
unitAmount: 9990
quantity: 1
addedAt: '2025-06-01T13:45:30.000Z'
removedAt: null
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Assinatura não encontrada
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Subscription not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````