Generic revenue API

Send payments and refunds from any processor FounderHQ has no connection for. One request per money event.

Endpoint

POST https://i.getfounderhq.com/api/revenue
authorization: Bearer fhq_sk_XXXX
content-type: application/json

FounderHQ answers 202 as soon as the command is stored. Normalization, matching, and attribution happen after that, so a slow ledger never slows your checkout.

Using the Node SDK? events.captureRevenue(command) posts a payment or a refund and retries for you. It needs a transactionId, so send subscription state without a payment with a direct request.

Example

curl -X POST https://i.getfounderhq.com/api/revenue \
  -H "authorization: Bearer fhq_sk_XXXX" \
  -H "content-type: application/json" \
  -d '{
    "idempotencyKey": "acme:payment:pay_ABC123",
    "transactionId": "pay_ABC123",
    "transactionRefType": "payment_intent",
    "kind": "payment",
    "amountMinor": "4900",
    "currency": "USD",
    "occurredAt": "2026-05-23T09:15:00.000Z",
    "paymentRail": "razorpay",
    "environment": "live",
    "customerEmail": "jane@acme.com",
    "checkoutVisitorId": "6b1f0d64-1f0e-4e5a-9a2a-6b0f1d8c2e77",
    "providerCustomerId": "cust_42",
    "providerSubscriptionId": "sub_42",
    "subscription": {
      "status": "active",
      "interval": "P1M",
      "currentPeriodEnd": "2026-06-23T09:15:00.000Z",
      "plan": "growth"
    }
  }'

Response

{
  "ok": true,
  "deliveryId": "DELIVERY_ID",
  "status": "QUEUED",
  "created": true
}

Idempotency

idempotencyKey identifies the delivery. Reuse the same key on every retry of the same money event.

• Same key, same body: FounderHQ returns 202 with created: false. Nothing is counted twice.
• Same key, different body: FounderHQ returns 409. Pick a new key, or send the body you sent the first time.
• Different key, same transactionId, transactionRefType, and kind: FounderHQ still counts the money once. The transaction is what dedupes the economics.

Keys are scoped to the brand, not to the API key you send them with. Every secret key of a brand shares one idempotency space, one customer namespace, and one subscription namespace. Rotate a key and the next renewal still lands on the same customer and the same subscription.

Fields

subscription

Send this block on a recurring payment and FounderHQ drives MRR from it, the same way a connected provider does.

Rules FounderHQ enforces

Errors

Verify

1. Send a test payment with "environment": "test".
2. Confirm the response is 202 with "created": true.
3. Send the same body again. The response says "created": false.
4. In FounderHQ, open Analytics → People and open the customer. The payment is on their Revenue tab with your amount. When you sent checkoutVisitorId, it also counts for the channel that brought them, in the Channel card of Analytics → Overview.

Subscription state without a payment

Send kind: "subscription" for a trial, pause, failed renewal, end, or confirmed free service period. These commands do not create cash revenue. Do not send a zero payment as a substitute.

{
  "kind": "subscription",
  "idempotencyKey": "acme:sub_42:free:2026-09",
  "providerSubscriptionId": "sub_42",
  "occurredAt": "2026-09-01T00:00:00.000Z",
  "currency": "USD",
  "status": "active",
  "period": {
    "kind": "free",
    "startsAt": "2026-09-01T00:00:00.000Z",
    "endsAt": "2026-10-01T00:00:00.000Z"
  }
}

For a state change without a confirmed free period, use "period": { "kind": "lifecycle" }. Status can be trialing, active, past_due, paused, canceled, or expired. Use canceled or expired only when entitlement ends. A scheduled cancellation must keep active until then. Use the same paymentRail, merchantAccountId, and environment as the payments. A changed revision needs a new idempotency key. providerRevisionAt and providerRevisionKey can record the provider's revision identity.

MRR stays zero before the first positive recurring payment. A confirmed free period after payment reduces MRR to zero; the next paid period increases it. Refund commands change cash and do not replace subscription MRR. A wallet top-up is cash only; do not describe it as recurring subscription service.

For a partial mid-period payment, set subscription.periodKind to proration. It changes cash but retains the previous recurring baseline. The default is full, for a full recurring service period. The first full positive payment establishes MRR.

AI agent or LLM? Read this page as markdown