Finance

The finance module is a lightweight ERP attached to your stores: procurement, accounts payable, COD receivables, cash accounts and reports. Everything lives under /v1/finance and requires a bearer token.

• Project-scoped. Every request carries a projectId (query param on reads, body field on writes). A project groups one or more stores (store.projectId) and is shared with inventory; list yours via GET /v1/inventory/projects.
• Permissions. The store owner can do everything. Members need the finance.read permission for reads and finance.write for writes (enforced per store role). The finance module must also be enabled for the store (billing entitlement).
• Lists accept page, limit, search and the filterator, and return the standard paginator envelope. Batch endpoints (:batchDelete, :batchPay, …) take { projectId, names, returnPartialSuccess? } and return the partial-success envelope.

Purchase-to-pay flow

Posting a receipt is one transaction with three effects: receipt lines become inventory objects (batch buckets carrying unit_cost in metadata), a reason: "receive" movement is recorded per line, and an open supplier bill is created for the total. Posting is idempotent. Rules that follow from this:

• Batch-cost invariant — an existing batch only accepts stock-in at the same unitCost; receiving at a different cost fails with BATCH_COST_MISMATCH (use a different batch).
• Voiding a posted receipt reverses the stock-in. It fails with RECEIPT_REVERSE_BLOCKED if quantity was already reserved or sold, and with BILL_NOT_OPEN if the bill has payments — pass { "voidPayments": true } to void those payments in the same transaction.
• Purchase orders move through draft, sent, partial, received, cancelled; invalid transitions fail with INVALID_STATE_TRANSITION. Receipts don't require a PO (purchaseOrderId is optional).

At a glance

All endpoints require Bearer auth.

Suppliers

Purchase orders

Purchase receipts

Supplier bills & payments (AP)

Bills have no update or delete — totals are managed through payments and voids.

Receivables & customer payments (AR)

Receivables are derived from open COD orders — read-only rows keyed by order id.

Financial accounts & transfers

Expenses & other income

Both follow the same CRUD shape; categories are simple named trees (parentId).

Reports & reset

Reports are cached server-side and invalidated on writes.

Examples

Create a supplier:

curl -X POST "https://api.feeef.org/v1/finance/suppliers" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "PROJECT_ID", "name": "Atlas Textiles", "paymentTerms": "NET30" }'

Create a purchase order and send it:

curl -X POST "https://api.feeef.org/v1/finance/purchase-orders" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "supplierId": "SUPPLIER_ID",
    "items": [{ "sku": "tshirt/red/m", "qtyOrdered": 50, "unitCost": 950 }]
  }'

curl -X POST "https://api.feeef.org/v1/finance/purchase-orders/PO_ID/send?projectId=PROJECT_ID" \
  -H "Authorization: Bearer $FEEEF_TOKEN"

Receive the goods — create a receipt and post it (stock-in + bill):

curl -X POST "https://api.feeef.org/v1/finance/purchase-receipts" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "supplierId": "SUPPLIER_ID",
    "purchaseOrderId": "PO_ID",
    "lines": [{ "sku": "tshirt/red/m", "qtyReceived": 50, "unitCost": 950, "batch": "B-2026-08" }]
  }'

curl -X POST "https://api.feeef.org/v1/finance/purchase-receipts/RECEIPT_ID/post?projectId=PROJECT_ID" \
  -H "Authorization: Bearer $FEEEF_TOKEN"

Pay the supplier bill from a financial account:

curl -X POST "https://api.feeef.org/v1/finance/supplier-bills/BILL_ID/pay" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "PROJECT_ID", "financialAccountId": "ACCOUNT_ID", "amount": 47500 }'

Collect a COD payment against an order:

curl -X POST "https://api.feeef.org/v1/finance/orders/ORDER_ID/collect" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "PROJECT_ID", "financialAccountId": "ACCOUNT_ID", "amount": 3200 }'

Notes

• PDF endpoints respond with { "fileUrl": "https://…" } — a hosted PDF, not a binary body.
• POST /v1/finance/expenses is soft-deprecated: it records the expense as a native finance transfer (type: "expense") and returns that transfer row. Prefer /v1/finance/transfers for new integrations.
• Payments (supplier and customer) are immutable — correct mistakes by voiding, never editing.
• The general-ledger endpoints (gl-accounts, journal-entries, reports/trial-balance, reports/balance-sheet, accounting-periods) are retired; the routes are disabled even though older SDK builds still expose wrapper methods for them.