Skip to main content
Uma assinatura (sub_) é o contrato recorrente com um cliente: ela guarda o que se cobra, de quanto em quanto tempo e por qual forma de pagamento, e emite uma fatura a cada ciclo. Pode ser instanciada a partir de um plano ou montada com itens avulsos, informados na criação.
Todas as rotas exigem o header x-api-key. Veja Autenticação. Os exemplos usam a base URL de sandbox https://api.sandbox.z2pay.com/v1.

​
Endpoints

Cada endpoint tem a sua página, com os campos aceitos, os exemplos e o playground para testar.
A criação e as sete ações aceitam o header Idempotency-Key para repetir a requisição com segurança. Veja Convenções.

​
Como uma assinatura nasce

O estado inicial é consequência do que você envia, não uma escolha. Não existe campo status na criação: a combinação de forma de pagamento, período de teste e adesão decide em que ponto do ciclo de vida a assinatura entra. A tabela dessa decisão está em Criar assinatura. O que importa aqui é o que distingue os três pontos de entrada:
  • active — há forma de pagamento e nada a esperar. A primeira fatura é emitida e cobrada.
  • trialing — há período de teste. A primeira fatura só nasce quando o teste acaba, mesmo que a forma de pagamento já esteja cadastrada.
  • incomplete e pending_enrollment — falta algo. A assinatura existe, mas ainda não cobra ciclo nenhum: na primeira falta a forma de pagamento; na segunda, o pagamento da adesão.

​
Do incomplete ao active

Uma assinatura incomplete existe mas não tem como cobrar. Só uma coisa a tira desse estado: anexar uma forma de pagamento por POST /subscriptions/{id}/payment-method, que a ativa na hora e emite a primeira fatura.
A incomplete comum não expira. Ela fica assim indefinidamente, até ganhar forma de pagamento ou ser cancelada à mão. A única com prazo é a que nasceu de um teste com requiresPaymentMethod e sem forma de pagamento: essa tem incompleteExpiresAt (cerca de 23 horas) e, vencido o prazo, vai para o estado terminal incomplete_expired.Isso significa que uma incomplete esquecida não vira nada sozinha — ela não some, não cancela e não cobra. Se a sua integração cria assinaturas sem forma de pagamento, é preciso acompanhá-las.
O link hospedado de troca de cartão não ativa uma incomplete. Ele responde 409 nesse estado, porque existe para o cliente final trocar o cartão de uma assinatura que já está ativa — ver Faturas. Para o cliente final pagar e ativar, o caminho é o Checkout com mode: "subscription".

​
Os dez estados

Nem todo estado tem rota que o produza. past_due, unpaid, completed, incomplete_expired e a transição de trialing para active acontecem sozinhos, pelo motor de cobrança. Pela API você provoca pausa, retomada, cancelamento e a ativação de uma incomplete — o resto é consequência do que o tempo e os pagamentos fizerem.
unpaid não é o fim. É o estado em que a cobrança automática desistiu, mas o contrato continua de pé: o lojista pode reativá-lo pelo painel, e a assinatura volta a active cobrando um ciclo novo. Uma integração que trate unpaid como terminal vai perder a reativação.
A régua de inadimplência que move past_due está em Ciclos.

​
Veja também

Planos e Preços

O catálogo de onde a assinatura é instanciada.

Faturas

O que a assinatura emite a cada ciclo.

Ciclos

Cadência, âncoras e as datas de cada cobrança.

Clientes

Quem assina.