W3builders
HomePricingCase StudiesBlogsAboutDevelopers
Services
Web
App
Other
Products
W3builders AOPLive
Quko AppsComing Soon
All solutions →
AOP API

AOP API/Documents & Invoices

Create Document

POST/finance/documents
JWT bearerPrimary write endpoint

Record a new invoice / estimate / note. The core "record financial data" endpoint.

Endpoint

POSThttps://api.w3builders.com/v1/finance/documents

Request body

  • type (required — one of the 8 values above)
  • project_id, client_id (optional)
  • reference, status (default draft), issue_date (default today), due_date (default issue_date + settings.default_due_days), valid_until
  • client_name, client_email, client_phone, client_address, client_gstin, client_state, client_state_code
  • currency (default tenant default), exchange_rate (default 1)
  • discount_type: none | percent | amount, discount_value
  • place_of_supply (auto-filled from client_state if omitted — drives CGST/SGST vs IGST)
  • line_items[]: { catalog_item_id?, name, description?, hsn_sac?, quantity, unit?, rate, discount_type?, discount_value?, tax_rate?, tax_type? } — server always recomputes tax/totals
  • template, brand_color, watermark, show_signature, show_stamp, show_bank_details, show_qr
  • notes, terms, header_text, footer_text
  • linked_document_id — required when type = credit_note (must be an existing invoice you own)
  • Document number is auto-generated per tenant/type, reset every Indian financial year (Apr–Mar), e.g. INV/2026-27/003. Returns 422 FINANCE_SETTINGS_REQUIRED if settings aren't configured yet.
  • GST split (CGST+SGST vs IGST) is computed automatically from company_state_code vs place_of_supply — forced to 0 if the tenant isn't GST-registered.
  • Subject to your plan's monthly document quota (finance_docs_pm).
  • credit_note amount cannot exceed the linked invoice's remaining due — 400 if it does. On success it posts a journal entry and reduces the invoice's amount_due.
  • Creating an invoice automatically posts a balanced double-entry journal entry (Dr Accounts Receivable / Cr Income + tax liability) — you do not need to call the journals endpoint separately.
  • A public portal_token is generated for client-facing viewing/approval/PDF access (see Client Portal).

Response parameters

Create Document
curl -X POST https://api.w3builders.com/v1/finance/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "invoice",
  "client_name": "Acme Co",
  "client_email": "billing@acme.com",
  "client_state": "Maharashtra",
  "line_items": [
    {
      "name": "Design retainer",
      "quantity": 1,
      "rate": 45000,
      "tax_rate": 18
    }
  ],
  "notes": "Thanks for your business!"
}'
{
  "document": {
    "id": 4821,
    "number": "INV/2026-27/004",
    "type": "invoice",
    "status": "draft",
    "client_name": "Acme Co",
    "total": 53100,
    "amount_paid": 0,
    "amount_due": 53100,
    "portal_token": "9f2c1a..."
  }
}
Was this page helpful?
PreviousCalculate Document Totals
NextGet Document