Numbered invoices for GoCommerce

What it does

Configuration

One setting is required: the seller’s name. All five are Config fields — this module has no settings in the admin’s panel — so they are set in your own main(), or through the reference binary’s -invoices flag and its three environment variables.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Choose the number formatThe default is INV-{year}-{seq:05}, which gives INV-2026-00001. Settle yours before the first invoice; the count restarts at 1 each calendar year.
2. Install the moduleImport it and pass invoices.New to gocommerce.New with at least SellerName, as below — or run the reference binary with -invoices and the INVOICES_ variables.
3. Take a paymentEvery order that reaches paid gets its invoice. On start-up, paid orders that have none are caught up.
4. Print or fetch itOpen it from the order or the Invoices screen in the admin, or GET /api/admin/x/invoices/{orderId} — HTML to print, or JSON with Accept: application/json.

import (
	"github.com/itswadesh/gocommerce/core"
	"github.com/itswadesh/gocommerce/ext/invoices"
)

app, err := gocommerce.New(cfg,
	invoices.New(invoices.Config{
		SellerName:   "Example Ltd",
		NumberFormat: "INV-{year}-{seq:05}",
	}),
)

How it works

• Issued on payment, once

  The module subscribes to order.paid. Event delivery is at least once, so a unique constraint on the order id turns a repeated event into a no-op rather than a second invoice.

• Gapless, per year

  The number comes from a counter row per year, taken under a lock inside the transaction that writes the invoice. A rollback gives the number back, which a PostgreSQL sequence would not.

• Your format

  NumberFormat expands {year} — the UTC calendar year — and {seq}, with {seq:05} padding to five digits. Two deliveries at once queue for the counter rather than share a number.

• A snapshot of the order

  The order is stored as JSON as it stood when the invoice was issued, so later edits to the order do not change the invoice’s lines or totals.

• Nothing missed at start-up

  When the store starts, the module looks for paid orders with no invoice and issues them — the safety net under at-least-once delivery.

• HTML or JSON, behind a right

  The invoice route answers with a printable page, or JSON when asked. Reading needs the invoices.read right, which the manager and staff roles hold by default.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• No tax lineThe order’s tax is in the snapshot, but the printed invoice shows subtotal, shipping, discount and total only. With tax-exclusive prices, the lines shown do not add up to the total.
• Amounts in minor unitsThe page prints every amount as a whole number of minor units — INR 123450 for ₹1,234.50 — and says so at its foot.
• Seller details are read liveThe seller block comes from Config when an invoice is viewed, not from the snapshot. Change the address and every past invoice shows the new one.
• No PDF, no emailThe invoice is an HTML page to print or JSON to process. The module renders no PDF and does not send the invoice to the shopper.
• No credit notesA refund issues nothing and changes nothing: the module listens for order.paid only.
• 500 at a time on start-upThe start-up catch-up issues invoices for at most 500 paid orders. A larger backlog is cleared over several restarts.