API Reference

Base URL: https://paypulseapp.com

All requests require a Bearer token in the Authorization header.

Authentication

Authorization: Bearer pp_live_<key>

Test mode keys (pp_test_...) only see test-mode data.

Response envelope

Successful responses:

{ "data": { ... }, "meta": { "request_id": "req_..." } }

Paginated responses add has_more and next_cursor:

{ "data": [...], "meta": { "request_id": "...", "has_more": true, "next_cursor": "..." } }

Errors:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "...",
    "doc_url": "https://developers.paypulseapp.com/errors/invalid_api_key",
    "request_id": "req_..."
  }
}

Endpoints

Identity

• GET /v1/me — returns the calling user, plan, scopes, rate-limit info.

Metrics

• GET /v1/metrics/current — latest snapshot for the primary connection.
• GET /v1/metrics/timeseries?metric=mrr&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD — daily points for one metric.
• GET /v1/metrics/snapshots — paginated list of daily snapshots.
• GET /v1/metrics/snapshots/{id} — one snapshot by ID.

Valid metric values: mrr, arr, trial_mrr, past_due_mrr, churn_rate, ltv, active_subs, churned_customers, new_mrr, expansion_mrr, contraction_mrr, churned_mrr.

Subscriptions

• GET /v1/subscriptions — list. Query: cursor, limit (1–100), status.
• GET /v1/subscriptions/{id} — get by processor subscription ID.

Status values normalize to: trialing, active, past_due, canceled, paused.

Customers

• GET /v1/customers — list. Customer IDs are hashed; the PayPulse API never returns raw emails or names.
• GET /v1/customers/{id} — get by hashed ID.
• GET /v1/customers/{id}/subscriptions — subscriptions belonging to that customer.

Connections

• GET /v1/connections — list your linked Stripe / Braintree connections.
• GET /v1/connections/{id} — get one by ID.

Billing

• GET /v1/billing/portal — returns a Stripe customer-portal URL for managing your PayPulse subscription.

Rate limits

Headers on every response:

Error types