PayZu GatewayRecorrência

Consultar assinaturas


Nesta páginaConsulte uma assinaturaListe as assinaturasErros desta operação

Leia o status, as datas de cobrança e o cancelamento de uma assinatura, ou liste as assinaturas da conta.

Consulte uma assinatura

bash
curl "https://api.sandbox.payzu.dev/v1/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Referência: Consultar uma assinatura

CampoO que traz
statusincomplete, active ou canceled.
credit_cardO cartão da assinatura, com card.id só quando o cartão está salvo. Vem null no Pix.
billingA data-base dos ciclos em anchor_at, a próxima cobrança em next_at, a data do cancelamento em canceled_at e as renovações recusadas seguidas em renewal_failures. Na assinatura cancelada, next_at vem null.
graceO início e o fim da carência, em started_at e ends_at.
cancellationNa assinatura cancelada, o motivo em reason e a sua observação em note.
previous_cancellationsOs cancelamentos desfeitos, do mais novo para o mais antigo, cada um com canceled_at, reason, note e reactivated_at.
planO id e o name do plano de origem. Vem null na assinatura avulsa.
discountO desconto da assinatura, que vale nos primeiros cycles ciclos.

O significado de cada status e de cada motivo está em Ciclo da assinatura, e o prazo da carência, em Carência.

Trecho de uma assinatura em carência
{
  "status": "active",
  "billing": {
    "anchor_at": "2026-11-11T03:00:00.000Z",
    "next_at": "2026-12-11T15:20:59.362Z",
    "canceled_at": null,
    "renewal_failures": 1
  },
  "grace": {
    "started_at": "2026-12-11T15:21:03.871Z",
    "ends_at": "2026-12-14T15:20:59.362Z"
  }
}

Liste as assinaturas

bash
curl "https://api.sandbox.payzu.dev/v1/subscriptions?status=active&plan_id=plan_oOsn4Cs4eayZ3LoytwzErn" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Referência: Listar as assinaturas

A lista traz items e next_cursor, da assinatura mais nova para a mais antiga, com cada item igual à consulta. A paginação é por cursor, como em Paginação.

FiltroO que traz
statusAs assinaturas nesse status.
plan_idAs assinaturas de um plano. As avulsas ficam de fora.
customer_idAs assinaturas de um cliente.
next_from, next_toO dia da próxima cobrança.
created_from, created_toO dia da criação.
searchBusca no código da assinatura e no nome, no e-mail ou no documento do cliente.

Os dias vão no formato AAAA-MM-DD, no fuso de São Paulo, e incluem o dia inteiro. Parâmetro que a lista não tem é ignorado.

Erros desta operação

CódigoHTTPMensagem
-404Assinatura não encontrada para o id informado.
PZ034404Recorrência não ativada para esta conta.

Os erros de autenticação e de validação estão no Catálogo de erros.