Objetos de Resposta

Objeto Subscription

Estrutura completa de uma assinatura retornada pela API:

{
  "id": 123,
  "status": "ACTIVE",
  "billingCycle": "MONTHLY",
  "amount": 5000,
  "nextBillingDate": "2026-03-24T15:30:00.000Z",
  "trialEndsAt": null,
  "startedAt": "2026-02-24T15:30:00.000Z",
  "cancelledAt": null,
  "customerEmail": "joao.santos@example.com",
  "customerName": "João Silva Santos",
  "customerDocument": "12345678900",
  "customerPhone": "5511999999999",
  "paymentMethod": "PIX",
  "lastPaymentDate": "2026-02-24T15:30:00.000Z",
  "lastPaymentStatus": "PAGO",
  "totalBillings": 1,
  "successfulBillings": 1,
  "failedBillings": 0,
  "product": {
    "id": 456,
    "name": "Assinatura Premium Mensal"
  },
  "metadata": {
    "itemTitle": "Assinatura Premium Mensal",
    "customerPhone": "5511999999999"
  },
  "createdAt": "2026-02-24T15:30:00.000Z",
  "updatedAt": "2026-02-24T15:35:00.000Z"
}

Campos

integer

required

ID único da assinatura

status

string

required

Status atual da assinatura. Valores possíveis: PENDING, ACTIVE, TRIALING, PAUSED, CANCELLED, PAST_DUE, EXPIRED

billingCycle

string

required

Ciclo de cobrança. Valores possíveis: WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY

amount

integer

required

Valor da assinatura em centavos (ex: 5000 = R$ 50,00)

nextBillingDate

string

required

Data da próxima cobrança (ISO 8601). null se cancelada ou expirada.

trialEndsAt

string

Data de término do período de trial (ISO 8601). null se não houver trial.

startedAt

string

Data de início da assinatura (ISO 8601). null se ainda não ativada.

cancelledAt

string

Data de cancelamento (ISO 8601). null se não cancelada.

customerEmail

string

required

Email do cliente assinante

customerName

string

required

Nome completo do cliente assinante

customerDocument

string

Documento do cliente (CPF ou CNPJ)

customerPhone

string

Telefone do cliente

paymentMethod

string

required

Método de pagamento. Valores possíveis: PIX, CREDIT_CARD

lastPaymentDate

string

Data do último pagamento (ISO 8601). null se nunca houve pagamento.

lastPaymentStatus

string

Status do último pagamento. Valores possíveis: PAGO, PENDENTE, RECUSADO, FALHA

totalBillings

integer

required

Total de cobranças realizadas

successfulBillings

integer

required

Total de cobranças bem-sucedidas

failedBillings

integer

required

Total de cobranças que falharam

product

object

Dados do produto associado à assinatura

product.id

integer

ID do produto

product.name

string

Nome do produto

metadata

object

Metadados adicionais da assinatura

createdAt

string

required

Data de criação da assinatura (ISO 8601)

updatedAt

string

required

Data da última atualização (ISO 8601)

Objeto Subscription na Resposta de Criação

Ao criar uma transação com assinatura, os dados da assinatura são retornados dentro do objeto sale.subscription:

{
  "message": "Venda criada com sucesso",
  "sale": {
    "id": 4607,
    "amount": "5000",
    "status": "PENDENTE",
    "paymentMethod": "PIX",
    "customer": { ... },
    "payment": { ... },
    "createdAt": "2026-02-24T15:30:00.000Z",
    "subscription": {
      "id": 123,
      "status": "PENDING",
      "billingCycle": "MONTHLY",
      "amount": 5000,
      "nextBillingDate": "2026-03-24T15:30:00.000Z",
      "trialEndsAt": null,
      "customerEmail": "joao.santos@example.com",
      "customerName": "João Silva Santos"
    }
  }
}

Campos do sale.subscription

integer

required

ID único da assinatura criada

status

string

required

Status inicial da assinatura (geralmente PENDING para PIX, ACTIVE para cartão aprovado)

billingCycle

string

required

Ciclo de cobrança configurado

amount

integer

required

Valor da assinatura em centavos

nextBillingDate

string

required

Data da próxima cobrança (ISO 8601)

trialEndsAt

string

Data de término do trial (ISO 8601). null se não houver trial.

customerEmail

string

required

Email do cliente assinante

customerName

string

required

Nome do cliente assinante

Nota: O campo subscription só estará presente na resposta quando subscription.enabled: true for enviado na requisição.

Objeto Metrics

Retornado pelo endpoint de métricas de assinaturas:

{
  "total": 150,
  "active": 120,
  "cancelled": 25,
  "paused": 5,
  "mrr": 6000.00,
  "arr": 72000.00,
  "churnRate": 2.5
}

Campos das Métricas

total

integer

required

Total de assinaturas criadas

active

integer

required

Quantidade de assinaturas ativas (status ACTIVE ou TRIALING)

cancelled

integer

required

Quantidade de assinaturas canceladas

paused

integer

required

Quantidade de assinaturas pausadas

mrr

number

required

Monthly Recurring Revenue - Receita mensal recorrente em reais (R$)

arr

number

required

Annual Recurring Revenue - Receita anual recorrente em reais (R$)

churnRate

number

required

Taxa de cancelamento em porcentagem (%)

Nota: Os valores de mrr e arr são retornados em reais (não em centavos), já formatados para exibição.

Status das Assinaturas

O campo status indica o estado atual da assinatura no sistema. Abaixo estão todos os status possíveis:

PENDING

Quando ocorre:

Assinatura criada e aguardando primeiro pagamento
Status inicial após criação da transação com assinatura

O que significa:

A assinatura foi criada com sucesso
Aguardando confirmação do primeiro pagamento
Cliente ainda não pagou ou pagamento está sendo processado

Próximos status possíveis:

ACTIVE - Quando o pagamento for confirmado (sem trial)
TRIALING - Quando o pagamento for confirmado (com trial)
CANCELLED - Se cancelada antes do primeiro pagamento

ACTIVE

Quando ocorre:

Primeiro pagamento confirmado (sem período de trial)
Período de trial encerrado e cobrança confirmada
Assinatura reativada após pausa

O que significa:

A assinatura está ativa e funcionando
Cobranças recorrentes serão processadas automaticamente
Cliente tem acesso ao produto/serviço

Próximos status possíveis:

PAUSED - Se pausada manualmente
CANCELLED - Se cancelada
PAST_DUE - Se houver falha na cobrança
EXPIRED - Se atingir data de expiração

TRIALING

Quando ocorre:

Primeiro pagamento confirmado e há período de trial configurado
Cliente está no período de teste gratuito

O que significa:

A assinatura está em período de trial
Cliente tem acesso ao produto/serviço sem cobrança
Primeira cobrança ocorrerá após término do trial

Próximos status possíveis:

ACTIVE - Quando o trial terminar e cobrança for confirmada
CANCELLED - Se cancelada durante o trial
PAST_DUE - Se a cobrança pós-trial falhar

PAUSED

Quando ocorre:

Assinatura pausada manualmente pelo vendedor
Pausada por solicitação do cliente

O que significa:

A assinatura está temporariamente suspensa
Nenhuma cobrança será processada
Cliente pode perder acesso ao produto/serviço

Próximos status possíveis:

ACTIVE - Se reativada
CANCELLED - Se cancelada enquanto pausada

CANCELLED

Quando ocorre:

Cancelamento solicitado pelo vendedor ou cliente
Cancelamento automático após múltiplas falhas de cobrança
Cancelamento por política da plataforma

O que significa:

A assinatura foi encerrada permanentemente
Nenhuma cobrança futura será processada
Cliente perde acesso ao produto/serviço

Próximos status possíveis:

Nenhum (status final)

PAST_DUE

Quando ocorre:

Falha na cobrança recorrente
Cartão recusado ou PIX não pago
Múltiplas tentativas de cobrança falharam

O que significa:

A assinatura está em atraso
Sistema tentará cobrar novamente
Cliente pode perder acesso temporariamente

Próximos status possíveis:

ACTIVE - Se o pagamento for regularizado
CANCELLED - Se não for regularizado após período de graça

EXPIRED

Quando ocorre:

Assinatura atingiu data de expiração definida
Período contratado encerrou

O que significa:

A assinatura chegou ao fim natural
Nenhuma cobrança futura será processada
Cliente perde acesso ao produto/serviço

Próximos status possíveis:

Nenhum (status final)

Fluxo de Status Típico

Assinatura sem Trial

PENDING → ACTIVE → CANCELLED/EXPIRED
              ↓
          PAST_DUE → ACTIVE (regularizado)
              ↓
          CANCELLED (não regularizado)

Assinatura com Trial

PENDING → TRIALING → ACTIVE → CANCELLED/EXPIRED
                        ↓
                    PAST_DUE → ACTIVE (regularizado)
                        ↓
                    CANCELLED (não regularizado)

Assinatura com Pausa

ACTIVE → PAUSED → ACTIVE (reativada)
            ↓
        CANCELLED

Ciclos de Cobrança

Ciclo	Código	Intervalo	Exemplo
Semanal	`WEEKLY`	7 dias	Toda segunda-feira
Quinzenal	`BIWEEKLY`	14 dias	A cada 2 semanas
Mensal	`MONTHLY`	30 dias	Todo dia 15
Trimestral	`QUARTERLY`	90 dias	Jan, Abr, Jul, Out
Semestral	`SEMIANNUAL`	180 dias	Jan, Jul
Anual	`YEARLY`	365 dias	Todo dia 1º de janeiro

Nota: A data da próxima cobrança é calculada a partir da data do último pagamento confirmado, somando o intervalo do ciclo.

Começando

MCP (Model Context Protocol)

Transações

Assinaturas

Transferências

Saldo

Seller

Objeto Subscription

Campos

Objeto Subscription na Resposta de Criação

Campos do sale.subscription

Objeto Metrics

Campos das Métricas

Status das Assinaturas

PENDING

ACTIVE

TRIALING

PAUSED

CANCELLED

PAST_DUE

EXPIRED

Fluxo de Status Típico

Assinatura sem Trial

Assinatura com Trial

Assinatura com Pausa

Ciclos de Cobrança

Começando

MCP (Model Context Protocol)

Transações

Assinaturas

Transferências

Saldo

Seller

​Objeto Subscription

​Campos

​Objeto Subscription na Resposta de Criação

​Campos do sale.subscription

​Objeto Metrics

​Campos das Métricas

​Status das Assinaturas

​PENDING

​ACTIVE

​TRIALING

​PAUSED

​CANCELLED

​PAST_DUE

​EXPIRED

​Fluxo de Status Típico

​Assinatura sem Trial

​Assinatura com Trial

​Assinatura com Pausa

​Ciclos de Cobrança

Objeto Subscription

Campos

Objeto Subscription na Resposta de Criação

Campos do sale.subscription

Objeto Metrics

Campos das Métricas

Status das Assinaturas

PENDING

ACTIVE

TRIALING

PAUSED

CANCELLED

PAST_DUE

EXPIRED

Fluxo de Status Típico

Assinatura sem Trial

Assinatura com Trial

Assinatura com Pausa

Ciclos de Cobrança