Histórico do cliente

Retorna o histórico completo de atividade do cliente: estatísticas agregadas (LTV, ticket médio, valor em aberto, total estornado) mais as listas de assinaturas, faturas, transações de pagamento e refunds. Use para construir uma view 360° do cliente em telas de suporte, dunning ou churn analysis. Todos os valores monetários em **centavos**.

GET/v2/customers/:id/history

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

idstring (path, UUID)obrigatório

UUID do cliente.

Exemplo: c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a

Respostas

200

Histórico do cliente. O bloco stats agrega métricas de toda a vida do cliente na conta; as listas trazem os registros individuais. Valores em centavos.

Campos do stats:

ltv — soma de tudo que o cliente já pagou (lifetime value)
ticketMedio — ltv dividido pelo número de faturas pagas
overdueAmount — soma das faturas em atraso ainda em aberto
totalRefunded — soma do que já foi estornado em refunds aprovados

JSON

{
  "stats": {
    "ltv": 49000,
    "ticketMedio": 4900,
    "overdueAmount": 4900,
    "totalRefunded": 0,
    "activeSubscriptions": 1,
    "paidInvoicesCount": 10,
    "openInvoicesCount": 1
  },
  "subscriptions": [
    {
      "id": "sub_abc123",
      "offerId": "off_xyz789",
      "status": "ACTIVE",
      "amount": 4900,
      "billingCycle": "MONTHLY",
      "currentCycle": 10,
      "nextChargeAt": "2026-06-26T00:00:00.000Z",
      "createdAt": "2025-08-26T10:00:00.000Z"
    }
  ],
  "invoices": [
    {
      "id": "inv_111",
      "subscriptionId": "sub_abc123",
      "status": "PAID",
      "amount": 4900,
      "amountPaid": 4900,
      "paidAt": "2026-05-26T14:32:00.000Z",
      "createdAt": "2026-05-26T14:00:00.000Z"
    },
    {
      "id": "inv_112",
      "subscriptionId": "sub_abc123",
      "status": "OVERDUE",
      "amount": 4900,
      "amountPaid": 0,
      "dueDate": "2026-05-15T00:00:00.000Z",
      "createdAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "transactions": [
    {
      "id": "1234567",
      "invoiceId": "inv_111",
      "method": "PIX",
      "status": "APPROVED",
      "amount": 4900,
      "approvedAt": "2026-05-26T14:32:00.000Z"
    }
  ],
  "refunds": []
}

404

Cliente não encontrado.

JSON

{ "status": 404, "error": "Cliente nao encontrado" }

Exemplos

cURL

curl -X GET "https://api.pagnovo.com/v2/customers/c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a/history" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch(
  `https://api.pagnovo.com/v2/customers/${customerId}/history`,
  { headers: { Authorization: `Basic ${token}` } },
);

const history = await res.json();
console.log(`LTV: R$ ${(history.stats.ltv / 100).toFixed(2)}`);
console.log(`ticket medio: R$ ${(history.stats.ticketMedio / 100).toFixed(2)}`);
console.log(`em aberto: R$ ${(history.stats.overdueAmount / 100).toFixed(2)}`);
console.log(`faturas pagas: ${history.invoices.filter(i => i.status === "PAID").length}`);