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. Invoice creation happens automatically at the end of each billing period (driven by the subscription’s billing cycle). You can also generate a draft invoice on demand for any active subscription using the generate endpoint — useful for mid-cycle billing, one-click “bill now” flows, and previewing what a customer’s next invoice will look like.

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_..."

Generate a draft invoice

Turns a subscription’s tracked usage into a draft invoice you can preview, edit, or send. Line items and totals are computed server-side from the period’s real usage events plus any recurring, seat, or one-time charges on the plan. Method & URL:

POST /v1/invoices/generate

Body:

Field	Type	Required	Description
`customerId`	string	Yes	The customer being billed (their MarginFront UUID, not the external ID from your system).
`subscriptionId`	string	Yes	The subscription whose usage you want to turn into an invoice.
`billingPeriodStart`	string	No	ISO 8601 date. Defaults to the subscription’s current period start.
`billingPeriodEnd`	string	No	ISO 8601 date. Defaults to the subscription’s current period end.

When billingPeriodStart / billingPeriodEnd are omitted, the subscription’s current billing period is used — the right answer for “bill now” flows. Example:

curl -X POST https://api.marginfront.com/v1/invoices/generate \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "subscriptionId": "1f2e3d4c-5b6a-7980-1234-56789abcdef0"
  }'

What you get back (201 Created): the full draft invoice, including line items and totals. The invoice starts in draft status — it is not sent until you move it to issued (manually, or via the auto-finalize step at the end of the billing period). Common errors:

400 Bad Request: customerId or subscriptionId is missing or not a UUID.
401 Unauthorized: API key missing or wrong.
404 Not Found: the customer or subscription does not exist in this org, or the customer does not own that subscription.

Send an invoice email

Emails an invoice to the customer with a “Pay Now” button that opens Stripe Checkout pre-filled with the invoice details. Use this after /v1/invoices/generate to actually deliver the draft, or to re-send an invoice that has already been issued. The customer’s stored email address is used by default — pass recipientEmail to override (for example, to route the invoice to a different billing contact). Method & URL:

POST /v1/invoices/{invoiceId}/send

Body (all fields optional — omit the body entirely to send to the customer’s stored email with auto-generated subject and body):

Field	Type	Required	Description
`recipientEmail`	string	No	Override the destination address. Falls back to the customer’s stored email.
`subject`	string	No	Custom subject line. Default: `Invoice {number} from {your business name}`.
`message`	string	No	Optional note shown in a callout above the invoice details (for example, “Card on file will be charged”).

Example:

curl -X POST https://api.marginfront.com/v1/invoices/inv_abc123/send \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "[email protected]",
    "subject": "May usage invoice — auto-charge in 5 days",
    "message": "Card on file will be charged automatically."
  }'

What you get back (200 OK):

{
  "success": true,
  "message": "Invoice email sent successfully",
  "emailId": "msg_88c9a928",
  "recipientEmail": "[email protected]"
}

emailId is the provider’s message ID for delivery tracking. recipientEmail echoes back the address the email was actually sent to (after applying any override). Side effect — auto-finalize: if the invoice was still in draft status when this call landed, sending it auto-finalizes the status from draft to issued. This matches the behavior of the dashboard’s Send button and the end-of-period auto-finalize step. No separate “finalize” call is needed first. After payment: once the customer clicks the Stripe Checkout link in the email and pays, the invoice status flips to paid automatically via webhook. You do not need to poll or make a follow-up call to confirm. Common errors:

400 Bad Request: the invoice cannot be sent (for example, it is already paid or void).
401 Unauthorized: API key missing or wrong.
404 Not Found: no invoice with that ID exists in this org.

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.

Status	Meaning
`draft`	Still being built. Not yet sent. Amounts can still change. Does not count as billed revenue.
`pending`	Finalized and queued to send. Sitting in the outbox waiting for the send step.
`issued`	Sent to the customer. Awaiting payment. Counts as billed revenue.
`paid`	Customer paid in full. Counts as collected revenue.
`overdue`	Past the due date without full payment. Still counts as billed revenue; payment is late.
`void`	Canceled. Treated as if it never happened for billing purposes. Does not count toward billed or collected.
`refunded`	Was 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}`);

// Generate a draft invoice from a subscription's current billing period
const draft = await mf.invoices.generate({
  customerId: "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
  subscriptionId: "1f2e3d4c-5b6a-7980-1234-56789abcdef0",
});

console.log(`Draft ${draft.invoiceNumber}: $${draft.totalAmount}`);

// Email the draft to the customer. If the invoice is still in draft status,
// this also auto-finalizes it to "issued" as a side effect. The customer's
// stored email is used by default.
const sent = await mf.invoices.send(draft.id);
console.log(`Sent to ${sent.recipientEmail} (message id: ${sent.emailId})`);

// Override recipient + subject + add a custom note
await mf.invoices.send("inv_abc123", {
  recipientEmail: "[email protected]",
  subject: "May usage invoice — auto-charge in 5 days",
  message: "Card on file will be charged automatically.",
});

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.

​Invoices

​The endpoints

​List invoices

​Read one invoice

​Generate a draft invoice

​Send an invoice email

​Invoice statuses

​Refund flow

​Common errors

​Using the Node SDK

​Analytics vs invoices: which do I want?