Billing & invoices

Fieldproof bills your organisation once a month. When we finalize a month, its statement becomes immutable and a GST tax invoice is raised against it. These read-only endpoints let you pull both — statements for reconciliation, invoices (JSON or PDF) for your books.

GET /api/v1/partner/billing/statements
GET /api/v1/partner/billing/statements/{month}
GET /api/v1/partner/billing/statements/{month}/invoice
GET /api/v1/partner/billing/statements/{month}/invoice.pdf

{month} is an IST calendar month, YYYY-MM (e.g. 2026-09).

Signed like every request — GET, empty body, and the canonical PATH is the path without any query string (see signing). Rate limit is 60 requests/min per key; on 429 RATE_LIMITED honour Retry-After.

:::note What you see These endpoints return only what you are charged: billed line items, GST and the invoice. Fieldproof's internal figures — field-partner payouts and our margin — are never part of these responses. :::

Only finalized months appear here. A month we have not yet closed returns 404 STATEMENT_NOT_FOUND — it is not an error, just "not billed yet".

---

List statements

GET /api/v1/partner/billing/statements?limit=24

Param	Type	Default / limit	Meaning
limit	integer	default 24, max 60	How many recent months to return.

Newest month first.

200

{
  "success": true,
  "count": 1,
  "statements": [
    {
      "month": "2026-09",
      "status": "final",
      "currency": "INR",
      "pricingModel": "hybrid",
      "activity": {
        "collectedAmount": 100000,
        "payments": 1,
        "resolvedCases": 1,
        "completedVisits": 1,
        "collectedByBucket": { "0-30": 100000 }
      },
      "charges": {
        "commission": 5000,
        "caseFees": 100,
        "visitFees": 0,
        "retainer": 0,
        "minimumTopUp": 0,
        "adjustmentBroughtForward": 0,
        "adjustmentCarriedForward": 0,
        "subtotal": 5100,
        "gstPct": 18,
        "gstAmount": 918,
        "total": 6018
      },
      "invoice": {
        "number": "FP/26-27/0001",
        "issuedAt": "2026-10-05T06:30:00.000Z",
        "dueAt": "2026-10-20T06:30:00.000Z",
        "status": "issued",
        "sacCode": "997159",
        "amountReceived": 0
      },
      "finalizedAt": "2026-10-05T06:30:00.000Z"
    }
  ]
}

Charge lines. subtotal is the pre-GST billable amount; total = subtotal + GST. commission can be negative in a month dominated by refunds — when the net is negative we bill nothing that month and carry it forward as adjustmentCarriedForward (a ≤ 0 credit), which reappears next month as adjustmentBroughtForward. retainer is the minimum-monthly top-up applied when usage is below your retainer.

Invoice status. issued → part_paid → paid as receipts land; overdue is derived when an unpaid invoice is past dueAt.

One month's statement

GET /api/v1/partner/billing/statements/2026-09

Same object as one row of the list above, under statement.

200

{ "success": true, "statement": { "month": "2026-09", "...": "..." } }

404 STATEMENT_NOT_FOUND if that month is not finalized. 422 VALIDATION_FAILED if month is not YYYY-MM.

Tax invoice (JSON)

GET /api/v1/partner/billing/statements/2026-09/invoice

200

{
  "success": true,
  "invoice": {
    "number": "FP/26-27/0001",
    "issuedAt": "2026-10-05T06:30:00.000Z",
    "dueAt": "2026-10-20T06:30:00.000Z",
    "status": "issued",
    "month": "2026-09",
    "sacCode": "997159",
    "seller": { "legalName": "…", "gstin": "…", "pan": "…", "address": "…", "email": "…", "state": "…" },
    "buyer": { "legalName": "Your Org", "gstin": "27ZZZZZ9999Z1Z5", "address": "…", "email": "…" },
    "lines": [
      { "desc": "Collection commission", "amount": 5000 },
      { "desc": "Case resolution fees", "amount": 100 }
    ],
    "subtotal": 5100,
    "gstPct": 18,
    "gstAmount": 918,
    "total": 6018,
    "tds": { "section": "194H", "ratePct": 2, "expected": 102 },
    "netPayable": 5916,
    "received": { "gross": 0, "tds": 0, "settledAt": null },
    "notes": "…"
  }
}

Buyer identity (buyer.gstin, address, billing email) comes from your onboarding profile — tell us if it changes so invoices stay correct.

TDS is indicative. tds.expected is TDS under section 194H on the pre-GST subtotal, shown for convenience. Deduct as applicable under law and share the certificate; netPayable = total − tds.expected.

409 NO_INVOICE means the month is finalized but its invoice number has not been allocated yet (rare, transient) — retry shortly.

Tax invoice (PDF)

GET /api/v1/partner/billing/statements/2026-09/invoice.pdf

Returns the same invoice as a downloadable application/pdf (a Content-Disposition: attachment with the invoice number as the filename). Amounts are prefixed INR rather than the ₹ glyph, which PDF standard fonts do not carry.

curl

curl -sS \
  -H "Authorization: Bearer $API_KEY_ID" \
  -H "X-Fieldproof-Timestamp: $TS" \
  -H "X-Fieldproof-Signature: $SIG" \
  https://gig.fluxusforge.in/api/v1/partner/billing/statements/2026-09/invoice.pdf \
  -o invoice-2026-09.pdf

Errors

HTTP	error.code	When
401	UNAUTHORIZED	Missing/!valid Bearer key or signature headers.
404	STATEMENT_NOT_FOUND	That month is not finalized (or does not exist).
409	NO_INVOICE	Finalized, but invoice number not yet allocated.
422	VALIDATION_FAILED	month is not YYYY-MM.
429	RATE_LIMITED	Over 60 req/min — honour Retry-After.