Skip to main content

​
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. Valid values are draft, pending, issued, paid, overdue, void, refunded (see Invoice statuses below)
  • startDate / endDate: filter by invoice date range
  • limit / offset: pagination
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": "issued",
      "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

MarginFront invoices move through one of seven statuses over their lifetime. Every invoice in the API has its status field set to exactly one of these.
StatusMeaning
draftStill being built. Not yet sent. Amounts can still change. Does not count as billed revenue.
pendingFinalized and queued to send. Sitting in the outbox waiting for the send step.
issuedSent to the customer. Awaiting payment. Counts as billed revenue.
paidCustomer paid in full. Counts as collected revenue.
overduePast the due date without full payment. Still counts as billed revenue; payment is late.
voidCanceled. Treated as if it never happened for billing purposes. Does not count toward billed or collected.
refundedWas paid, then fully refunded. Counts as neither billed nor collected once it lands here.
The natural “happy path” is draft → pending → issued → paid. Most invoices go through exactly those four.

​
Refund flow

Refunds are recorded against a payment, not directly against the invoice. When you create a refund using POST /v1/invoices/:invoiceId/payments/:paymentId/refund, MarginFront records the refund and, if the refund covers the entire invoice, moves the invoice from paid to refunded. Partial refunds leave the invoice in paid and just reduce the net collected amount. Once an invoice is refunded:
  • It is excluded from collected revenue totals.
  • It is excluded from billed revenue totals (as if it had never been invoiced).
  • The underlying payment and refund records are preserved for audit.
The dashboard and SDK analytics endpoints already handle refunded correctly. If you are rolling your own accounting sync, treat refunded invoices the same way you would treat void invoices for revenue-recognition purposes.

​
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 analyticsUse invoices
”How much has this customer used so far this month?""What’s the final bill I’m sending them?”
Live projections, dashboardsAccounting, A/R, customer portals
Raw usage data, no taxes/discountsFinalized totals with taxes, discounts, prorations
Current period, real-timeCompleted 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.