Buscar assinatura por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/subscriptions/{id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
    }
  ]
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Subscription not found"
  }
}

GET

subscriptions

{id}

Buscar assinatura por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/subscriptions/{id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
    }
  ]
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Subscription not found"
  }
}

GET /subscriptions/:id Faz parte do recurso Assinaturas — 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.

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.

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

curl https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "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.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Path Parameters

string

required

ID da assinatura

Response

Assinatura com seus itens

string

Identificador único do registro.

number

object

Número do endereço.

Show child attributes

referenceCode

string | null

Código do contrato no sistema do integrador; pesquisável, sem unicidade.

customerId

string

ID do cliente associado ao registro.

customerEmail

string

E-mail do cliente.

customerName

string

Nome do cliente.

customerDocument

string

Documento do cliente (CPF ou CNPJ).

currency

string

Moeda no padrão ISO 4217 (ex.: BRL).

status

enum<string>

Status atual do registro (assinatura, fatura, plano ou slip de pagamento).

Available options:

incomplete,

incomplete_expired,

trialing,

active,

past_due,

unpaid,

paused,

canceled,

completed

billingGroupId

any | null

ID do grupo de cobrança ao qual o registro pertence; nulo se não agrupado.

currentPeriodStart

string<date-time>

Início do período de cobrança atual da assinatura (ISO 8601).

currentPeriodEnd

string<date-time>

Fim do período de cobrança atual da assinatura (ISO 8601).

nextInvoiceAt

string<date-time> | null

Data e hora prevista para a próxima fatura da assinatura (ISO 8601).

recurrence

object

Regra de recorrência (intervalo, unidade e âncora do ciclo).

Show child attributes

collectionMethod

enum<string>

Como a fatura é cobrada. Hoje só a cobrança automática na forma de pagamento padrão.

Available options:

charge_automatically

collectionTiming

enum<string>

Momento da cobrança do ciclo: prepaid (no início) ou postpaid (no fim).

Available options:

prepaid,

postpaid

invoiceGenerationMode

enum<string>

Modo de geração de faturas: just_in_time (a cada ciclo) ou upfront (todas antecipadas).

Available options:

just_in_time,

upfront

cancelAtPeriodEnd

boolean

Indica se a assinatura será cancelada ao fim do período atual.

canceledAt

any | null

Data e hora do cancelamento; nula se não cancelado (ISO 8601).

endedAt

any | null

Data e hora em que a assinatura foi efetivamente encerrada; nula se ainda ativa (ISO 8601).

cancellationReason

any | null

Motivo do cancelamento da assinatura.

pausedAt

any | null

Data e hora em que a assinatura foi pausada; nula se não pausada (ISO 8601).

pauseResumesAt

any | null

Data e hora agendada para a retomada automática da assinatura pausada (ISO 8601).

pauseReason

any | null

Motivo da pausa da assinatura.

trialEnd

any | null

Data e hora de término do período de teste; nula se sem trial (ISO 8601).

incompleteExpiresAt

any | null

Prazo para concluir o primeiro pagamento antes de a assinatura incompleta expirar (ISO 8601).

trialRemindersFired

any[]

Lembretes de fim do período de teste já disparados para a assinatura.

maxCycles

integer | null

Número máximo de ciclos da assinatura; nulo se não houver limite.

issuedCycles

integer

Número de ciclos já faturados (faturas emitidas) da assinatura.

completedCycles

integer

Número de ciclos já concluídos (pagos) da assinatura.

defaultPaymentMethodRef

object

Referência da forma de pagamento padrão usada para cobrar a assinatura.

Show child attributes

splitConfig

any | null

Configuração de divisão (split) dos valores entre recebedores; nula se sem split.

paymentBehavior

enum<string>

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.

Available options:

allow_incomplete,

error_if_incomplete

latestInvoiceId

string

ID da fatura mais recente gerada pela assinatura.

paymentUpdateToken

any | null

Token do link público para o cliente atualizar a forma de pagamento; nulo se não gerado.

paymentUpdateMethods

any | null

Formas de pagamento permitidas no link público de troca; nula se não habilitada.

metadata

object

Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

items

object[]

Itens que a assinatura cobra.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Buscar assinatura por ID

Exemplo

Authorizations

Path Parameters

Response

​Exemplo

Authorizations

Path Parameters

Response

Exemplo