Invoices

Read the bills MarginFront generates

Invoices

An invoice is a finalized bill — the document you send to a customer when it’s time to pay. MarginFront generates invoices automatically based on each customer’s subscription and logged usage events. The API lets you read those invoices back so you can display them in your own product, sync them to accounting tools, or hand them to your finance team.

Right now the invoice API is read-only through the public surface. Invoice creation happens automatically at the end of each billing period (driven by the subscription’s billing cycle). Manual invoice creation will come later.

---

The endpoints

List invoices

Method & URL:

GET /v1/invoices

Query parameters (all optional):

• customerExternalId — Filter to a single customer
• status — Filter by state ("draft", "open", "paid", "void", etc.)
• startDate / endDate — Filter by invoice date range
• limit / offset — Pagination

Check apps/api-nest/src/modules/sdk/dto/query-sdk-invoices.dto.ts for the current full list.

Example:

curl "https://api.marginfront.com/v1/invoices?customerExternalId=acme-001" \
  -H "x-api-key: mf_sk_test_..."

What you get back (200 OK):

{
  "data": [
    {
      "id": "inv_abc123",
      "customerExternalId": "acme-001",
      "status": "open",
      "total": 429.5,
      "currency": "USD",
      "periodStart": "2026-03-01T00:00:00.000Z",
      "periodEnd": "2026-03-31T23:59:59.999Z",
      "dueDate": "2026-04-30T00:00:00.000Z",
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ],
  "hasMore": false
}

---

Read one invoice

Method & URL:

GET /v1/invoices/{invoiceId}

Returns: The full invoice including all line items — what each signal cost, per-agent breakdowns, discounts applied, taxes, the works.

Example:

curl https://api.marginfront.com/v1/invoices/inv_abc123 \
  -H "x-api-key: mf_sk_test_..."

---

Invoice statuses

Status	Meaning
draft	Still being built, not yet shown to the customer
open	Finalized, sent to the customer, awaiting payment
paid	Customer paid in full
void	Canceled — shouldn’t be collected on
uncollectible	Payment attempts failed, written off

---

Common errors

• 401 Unauthorized — API key missing or wrong.
• 404 Not Found — No invoice with that ID exists in this org.

---

Using the Node SDK

// List recent invoices for a customer
const { data } = await mf.invoices.list({
  customerExternalId: "acme-001",
});

// Fetch a specific invoice
const invoice = await mf.invoices.get("inv_abc123");

console.log(`Amount due: $${invoice.total} ${invoice.currency}`);

---

Analytics vs invoices — which do I want?

Quick disambiguation since both expose “cost” numbers:

Use analytics	Use invoices
”How much has this customer used so far this month?"	"What’s the final bill I’m sending them?”
Live projections, dashboards	Accounting, A/R, customer portals
Raw usage data, no taxes/discounts	Finalized totals with taxes, discounts, prorations
Current period, real-time	Completed billing periods

If the number needs to match what lands on the customer’s credit card, use invoices. If it’s a “heads up, here’s what you’re using” display, use analytics.