Skip to main content
Gerencie suas assinaturas através dos endpoints disponíveis na API do ImperiumPay Gateway.

​
Listar Assinaturas

Liste todas as assinaturas do usuário autenticado com filtros e paginação.

​
Autenticação

​
X-Api-Public-Key
string
required
Sua chave pública da API
​
X-Api-Private-Key
string
required
Sua chave privada da API

​
Query Parameters

​
status
string
Filtrar por status. Valores possíveis: PENDING, ACTIVE, TRIALING, PAUSED, CANCELLED, PAST_DUE, EXPIRED
​
search
string
Buscar por email ou nome do cliente
​
startDate
string
Data inicial para filtro (formato: YYYY-MM-DD). Considera timezone de Brasília (UTC-3).
​
endDate
string
Data final para filtro (formato: YYYY-MM-DD). Considera timezone de Brasília (UTC-3).
​
page
integer
Número da página (padrão: 1)
​
limit
integer
Itens por página (padrão: 20, máximo: 100)
curl -X GET "https://api.imperiumpay.com.br/api/subscriptions" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "id": 123,
        "status": "ACTIVE",
        "billingCycle": "MONTHLY",
        "amount": 5000,
        "nextBillingDate": "2026-03-24T15:30:00.000Z",
        "trialEndsAt": null,
        "customerEmail": "joao.santos@example.com",
        "customerName": "João Silva Santos",
        "paymentMethod": "PIX",
        "product": {
          "id": 456,
          "name": "Assinatura Premium"
        },
        "createdAt": "2026-02-24T15:30:00.000Z"
      },
      {
        "id": 124,
        "status": "TRIALING",
        "billingCycle": "MONTHLY",
        "amount": 9900,
        "nextBillingDate": "2026-03-31T15:30:00.000Z",
        "trialEndsAt": "2026-03-03T15:30:00.000Z",
        "customerEmail": "maria@example.com",
        "customerName": "Maria Oliveira",
        "paymentMethod": "CREDIT_CARD",
        "product": {
          "id": 789,
          "name": "Plano Pro"
        },
        "createdAt": "2026-02-24T16:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

​
Buscar Assinatura por ID

Obtenha os detalhes completos de uma assinatura específica.

​
Path Parameters

​
id
integer
required
ID da assinatura
curl -X GET "https://api.imperiumpay.com.br/api/subscriptions/123" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

{
  "success": true,
  "data": {
    "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"
  }
}

​
Pausar Assinatura

Pause temporariamente uma assinatura ativa. Nenhuma cobrança será processada enquanto pausada.

​
Path Parameters

​
id
integer
required
ID da assinatura
curl -X POST "https://api.imperiumpay.com.br/api/subscriptions/123/pause" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

{
  "success": true,
  "message": "Assinatura pausada com sucesso",
  "data": {
    "id": 123,
    "status": "PAUSED",
    "pausedAt": "2026-02-24T18:00:00.000Z"
  }
}
Importante: Apenas assinaturas com status ACTIVE ou TRIALING podem ser pausadas.

​
Reativar Assinatura

Reative uma assinatura que foi pausada anteriormente.

​
Path Parameters

​
id
integer
required
ID da assinatura
curl -X POST "https://api.imperiumpay.com.br/api/subscriptions/123/resume" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

{
  "success": true,
  "message": "Assinatura reativada com sucesso",
  "data": {
    "id": 123,
    "status": "ACTIVE",
    "nextBillingDate": "2026-03-24T15:30:00.000Z",
    "resumedAt": "2026-02-25T10:00:00.000Z"
  }
}
Nota: Ao reativar, a próxima data de cobrança é recalculada a partir da data de reativação.

​
Cancelar Assinatura

Cancele permanentemente uma assinatura. Esta ação não pode ser desfeita.

​
Path Parameters

​
id
integer
required
ID da assinatura

​
Body Parameters (Opcionais)

​
reason
string
Motivo do cancelamento (para registro interno)
​
cancelImmediately
boolean
Se true, cancela imediatamente. Se false, cancela ao final do período atual. Padrão: true
curl -X POST "https://api.imperiumpay.com.br/api/subscriptions/123/cancel" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Solicitação do cliente",
    "cancelImmediately": true
  }'

{
  "success": true,
  "message": "Assinatura cancelada com sucesso",
  "data": {
    "id": 123,
    "status": "CANCELLED",
    "cancelledAt": "2026-02-24T18:00:00.000Z",
    "cancellationReason": "Solicitação do cliente"
  }
}
Atenção: O cancelamento é uma ação permanente e não pode ser desfeita. Para suspender temporariamente uma assinatura, use a opção de pausar.

​
Obter Métricas

Obtenha métricas SaaS das suas assinaturas (MRR, ARR, Churn Rate, etc.). 
curl -X GET "https://api.imperiumpay.com.br/api/subscriptions/metrics" \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

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

​
Campos das Métricas

CampoDescrição
totalTotal de assinaturas criadas
activeAssinaturas ativas (inclui ACTIVE e TRIALING)
cancelledAssinaturas canceladas
pausedAssinaturas pausadas
mrrMonthly Recurring Revenue em R$
arrAnnual Recurring Revenue em R$
churnRateTaxa de cancelamento em %
Nota: Os valores de mrr e arr são retornados em reais (não em centavos).

​
Códigos de Erro Comuns

Código HTTPCódigo de ErroDescrição
400INVALID_STATUSOperação não permitida para o status atual
400ALREADY_CANCELLEDAssinatura já foi cancelada
400ALREADY_PAUSEDAssinatura já está pausada
401UNAUTHORIZEDChaves de API inválidas
403FORBIDDENSem permissão para acessar esta assinatura
404NOT_FOUNDAssinatura não encontrada
500INTERNAL_ERRORErro interno do servidor