API Documentation

Website API Integration

Create an integration key and submit sales invoices directly against your tenant subdomain.

Overview

Nepal E-Billing is multi-tenant. Every organization uses its own tenant subdomain, so API calls must be sent to https://{sub_domain}.{base_url}, not the public marketing domain.

The sales invoice endpoint is authenticated with an active X-API-Key. Generate the key from Dashboard > Settings > API Keys and send it directly on the invoice request.

The generated raw_key is shown only once when the key is created, so store it in your secure server environment before leaving the settings page.

Sales invoice generation returns invoice_id and invoice_number after a successful request.

If your tenant is configured for PDF Ready Response, the success response can also include a generated invoice pdf_url.

Authentication

A Billing Admin can generate an integration key from Dashboard > Settings > API Keys. That settings entry is shown only when API integration is enabled for the tenant. The returned raw_key is shown only once after creation.

Send that key in the X-API-Key header on every invoice request.

Open Dashboard > Settings > API Keys as a Billing Admin.
Generate the key, copy the returned raw_key, and store it securely.
Send X-API-Key with the invoice payload to the sales invoice endpoint.

Sales invoice endpoint

Method: POST

Path: /invoices/sales-invoice-generation/

Authentication header: X-API-Key: <integration_api_key>

Content type: application/json

If customer_name is Cash In Hand, then payment_mode must be CA. In that case, a receipt voucher is created automatically.

Payload

The request body includes top-level customer and invoice fields plus a products array. At least one product row is required.

Top-level fields

customer_name

Required

Yes

Type

string

Notes

Customer or ledger display name. If it is exactly Cash In Hand, payment mode must be CA.

payment_mode

Required

Yes

Type

string

Notes

Supported in the current API: CA, CR, BA, QR, KH, ES, PO.

products

Required

Yes

Type

array

Notes

At least one product row is required.

phone_number

Required

Type

string

Notes

Recommended with customer_name to reduce duplicate client creation.

pan_number

Required

Type

string

Notes

Used to match or update the customer ledger if available.

alias_email

Required

Type

string

Notes

Current API field for customer email.

address

Required

Type

string

Notes

Stored against the customer ledger if provided.

notes

Required

Type

string

Notes

Saved on the created invoice.

invoice_date

Required

Type

YYYY-MM-DD

Notes

If omitted, the server uses the current tenant time.

Field	Required	Type	Notes
customer_name	Yes	string	Customer or ledger display name. If it is exactly Cash In Hand, payment mode must be CA.
payment_mode	Yes	string	Supported in the current API: CA, CR, BA, QR, KH, ES, PO.
products	Yes	array	At least one product row is required.
phone_number	No	string	Recommended with customer_name to reduce duplicate client creation.
pan_number	No	string	Used to match or update the customer ledger if available.
alias_email	No	string	Current API field for customer email.
address	No	string	Stored against the customer ledger if provided.
notes	No	string	Saved on the created invoice.
invoice_date	No	YYYY-MM-DD	If omitted, the server uses the current tenant time.

Product item fields

name

Required

Yes

Type

string

Notes

Product or service name. Missing products are auto-created as service items.

quantity

Required

Yes

Type

number

Notes

Must be greater than 0.

rate

Required

Yes

Type

number

Notes

Must be greater than or equal to 0.

taxable

Required

Type

boolean

Notes

If true, VAT is calculated for that line item.

discount_type

Required

Type

AMT | PER | NONE

Notes

Defaults to AMT when omitted.

discount

Required

Type

number

Notes

Non-negative. Percentage discounts must not exceed 100.

Field	Required	Type	Notes
name	Yes	string	Product or service name. Missing products are auto-created as service items.
quantity	Yes	number	Must be greater than 0.
rate	Yes	number	Must be greater than or equal to 0.
taxable	No	boolean	If true, VAT is calculated for that line item.
discount_type	No	AMT \| PER \| NONE	Defaults to AMT when omitted.
discount	No	number	Non-negative. Percentage discounts must not exceed 100.
category	No	string	Created if it does not already exist.
unit	No	string	Created if it does not already exist.

Examples

JSON

Invoice payload

{
  "customer_name": "Acme Corporation",
  "payment_mode": "CA",
  "phone_number": "9845000000",
  "pan_number": "999999999",
  "address": "Kathmandu, Nepal",
  "alias_email": "billing@acme.com",
  "notes": "Invoice generated from external order #SO-1048",
  "invoice_date": "2026-04-09",
  "products": [
    {
      "name": "Widget B",
      "quantity": 15,
      "rate": 9.99,
      "taxable": true,
      "discount_type": "AMT",
      "discount": 2.5,
      "category": "Gadgets",
      "unit": "piece"
    },
    {
      "name": "Service C",
      "quantity": 1,
      "rate": 150,
      "taxable": false
    }
  ]
}

cURL

Invoice request with cURL

curl --request POST \
  --url https://{sub_domain}.{base_url}/invoices/sales-invoice-generation/ \
  --header 'X-API-Key: <integration_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_name": "Acme Corporation",
    "payment_mode": "CA",
    "phone_number": "9845000000",
    "pan_number": "999999999",
    "address": "Kathmandu, Nepal",
    "alias_email": "billing@acme.com",
    "notes": "Invoice generated from external order #SO-1048",
    "invoice_date": "2026-04-09",
    "products": [
      {
        "name": "Widget B",
        "quantity": 15,
        "rate": 9.99,
        "taxable": true,
        "discount_type": "AMT",
        "discount": 2.5,
        "category": "Gadgets",
        "unit": "piece"
      },
      {
        "name": "Service C",
        "quantity": 1,
        "rate": 150,
        "taxable": false
      }
    ]
  }'

JavaScript

Invoice request with fetch

const invoiceResponse = await fetch(
  "https://{sub_domain}.{base_url}/invoices/sales-invoice-generation/",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.NEB_INTEGRATION_KEY ?? ""
    },
    body: JSON.stringify({
  "customer_name": "Acme Corporation",
  "payment_mode": "CA",
  "phone_number": "9845000000",
  "pan_number": "999999999",
  "address": "Kathmandu, Nepal",
  "alias_email": "billing@acme.com",
  "notes": "Invoice generated from external order #SO-1048",
  "invoice_date": "2026-04-09",
  "products": [
    {
      "name": "Widget B",
      "quantity": 15,
      "rate": 9.99,
      "taxable": true,
      "discount_type": "AMT",
      "discount": 2.5,
      "category": "Gadgets",
      "unit": "piece"
    },
    {
      "name": "Service C",
      "quantity": 1,
      "rate": 150,
      "taxable": false
    }
  ]
})
  }
);

const result = await invoiceResponse.json();
console.log(result.invoice_id, result.invoice_number);

JSON

Success response

{
  "invoice_id": "6d38446f-0bb1-4acb-9f5b-4c6fa35b8861",
  "invoice_number": "SA-000123"
}

Notes

Use alias_email for customer email in the invoice payload.
Match customers with customer_name plus at least one of phone_number, pan_number, or alias_email where possible.
Billing Admins can create and copy the key from Dashboard > Settings > API Keys.
If API integration is disabled for your tenant, the sales invoice integration endpoint returns403.
If the tenant subscription is expired, the sales invoice integration endpoint also returns403 until the subscription is renewed.
Some tenants are configured to include a generated invoice pdf_url in the success response. Do not depend on that field unless your tenant is using PDF Ready Response.
Store the integration key in server-side environment variables and do not expose it in public browser bundles.
If the browser will call the invoice API directly, your domain must be allowed by Nepal E-Billing CORS and web-app origin rules.
Keep tenant URL parts and credentials in environment variables, not hard-coded in the frontend bundle.