Create Invoice (Guide) - BillClap Developer

Detailed reference for POST /api/web/invoice/create-invoice. Use the interactive API playground to send test requests.

Endpoint

POST https://api.billclap.com/api/web/invoice/create-invoice

Your BillClap plan must include the API integration feature. See Authentication.

Authentication

Include your API token on every request:

Header	Value
`Content-Type`	`application/json`
`x-api-token`	Your API token from Settings → API Integration

Do not use Authorization: Bearer for this endpoint.

Request body

Top-level fields

Field	Type	Required	Description
`type`	string	Yes	Document type. Common values: `SALESINVOICE`, `QUOTATION`, `SALESRETURN`, `PURCHASEBILL`, `PURCHASERETURN`, `DELIVERYCHALLAN`, `ORDER`, `PURCHASEORDER`, `SELLORDER`, `SALEORDER`.
`issue_date`	string	Recommended	Invoice issue date (stored on the invoice record).
`due_date`	string	Optional	Payment due date.
`invoice_number`	string \| number	Optional	Custom invoice number. If omitted, the next number from invoice settings (with optional prefix) is used. Must be unique for the firm.
`receive_amount`	number	Optional	Amount received against the invoice. Used for payment-in/out and paid/partial status. Cannot exceed calculated `total_amount`.
`bank_id`	number	Optional	Bank account to record payment against. Defaults to the business default bank; a cash bank is created if none exists.
`party_detail`	object	Yes	Customer or supplier details. See Party detail.
`product_details`	array	Yes	Line items. At least one entry with `product_name` is expected. See Product details.
`additional_charges`	array	Optional	Extra charges with tax. See Additional charges.
`additional_discount`	number	Optional	Invoice-level discount applied before totals are finalized.
`autoRoundOffChecked`	boolean	Optional	When true, rounds `total_amount` to the nearest integer and sets `roundOffAmount`.
`is_bill_of_supply`	boolean	Optional	When true, marks the invoice as bill of supply (`'1'`), otherwise `'0'`.
`is_txn_wise_tax_enabled`	string	Optional	Transaction-wise tax flag (`'0'` or `'1'`).
`txn_wise_tax_pct`	string	Optional	Transaction-wise tax percentage when enabled.
`paymentIn_id`	number	Optional	Existing payment record id when upserting a linked payment.
`convert_invoice_id`	number	Optional	Source invoice id when converting documents (inventory).

Party detail

Either link an existing party or create/match one by mobile number or cash sale.

Field	Type	Required	Description
`party_id`	number	Conditional	Existing party id in your business. If valid, other fields are optional.
`party_name`	string	Recommended	Display name; used when creating a new party.
`mobile_no`	string	Conditional	Required when creating/finding a party unless `cash_sale` is used.
`cash_sale`	boolean	Conditional	Use the cash-sale party instead of mobile lookup. Sets received amount to full total when used with calculation flags.
`gst_no`	string	Optional	GSTIN.
`address`	string	Optional	Billing address line.
`city`	string	Optional	Billing city.
`state`	string	Optional	Billing state.
`country`	string	Optional	Billing country.
`pin_code`	string	Optional	Billing PIN code.

Validation rules enforced by the API:

party_detail must be a non-empty object.
If party_id does not resolve to a party, either mobile_no or cash_sale is required.
New parties are created as CUSTOMER for sales documents and SUPPLIER for purchase types (PURCHASEBILL, PURCHASERETURN, PURCHASEORDER).

Product details

Each element describes one line item. Entries without product_name are skipped.

Field	Type	Required	Description
`product_id`	number	Optional	Existing product id. If set, product is loaded from catalog.
`product_name`	string	Yes*	Product name. Used to match existing catalog product or create a new one.
`product_sell_price`	number	Conditional	Required when creating a new product. Unit price.
`product_gst`	number	Conditional	Required when creating a new product. GST rate (e.g. `18`).
`product_sell_price_tax_type`	string	Optional	`With Tax` (default) or `Without Tax`.
`product_hsn`	string	Optional	HSN/SAC code.
`product_quantity`	number	Optional	Quantity (default `1`).
`discount_type`	string	Optional	`RS` (default) for fixed rupee discount per unit, or percentage when not `RS`.
`product_discount`	number	Optional	Discount amount or percentage per line rules (default `0`).
`product_description`	string	Optional	Line description.

*Required on at least one line item you intend to bill. When no catalog match exists, the API creates a product using product_sell_price and product_gst. Purchase documents (PURCHASEBILL, PURCHASERETURN) use purchase pricing logic; others use sales pricing.

Additional charges

Field	Type	Required	Description
`chargeName`	string	Yes	Label for the charge.
`chargeValue`	number	Yes	Taxable charge amount before GST on the charge.
`tax`	number	Yes	Tax rate percent on the charge.
`hsn_code`	string	Optional	HSN for the charge.

Only items with both chargeValue and tax are included in totals.

Example request

curl -X POST 'https://api.billclap.com/api/web/invoice/create-invoice' \
  -H 'Content-Type: application/json' \
  -H 'x-api-token: YOUR_API_TOKEN' \
  -d '{
    "type": "SALESINVOICE",
    "issue_date": "2026-07-01",
    "due_date": "2026-07-15",
    "receive_amount": 1180,
    "party_detail": {
      "party_name": "Acme Traders",
      "mobile_no": "9876543210",
      "gst_no": "29ABCDE1234F1Z5",
      "address": "123 MG Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "country": "India",
      "pin_code": "560001"
    },
    "product_details": [
      {
        "product_name": "Consulting Service",
        "product_sell_price": 1000,
        "product_sell_price_tax_type": "With Tax",
        "product_gst": 18,
        "product_hsn": "998314",
        "product_quantity": 1
      }
    ],
    "additional_charges": [
      {
        "chargeName": "Packaging",
        "chargeValue": 50,
        "tax": 18,
        "hsn_code": "9985"
      }
    ]
  }'

Success response

HTTP 200 OK

{
  "result": {
    "status": true,
    "message": "Invoice created successfully",
    "invoice_id": 12345,
    "link": "https://app.billclap.com/preview/12345/abc123token",
    "code": 200
  }
}

Field	Description
`result.invoice_id`	Internal BillClap invoice id.
`result.link`	Shareable preview URL for the created document.
`result.message`	Human-readable success message.
`result.code`	Application status code (200 on success).

Error responses

Authentication and plan (before handler)

HTTP	Body	Cause
`401`	`{ "status": false, "message": "API token is required" }`	Missing `x-api-token` header.
`401`	`{ "status": false, "message": "Invalid token type" }`	Token is not an API integration token.
`401`	`{ "status": false, "message": "<jwt error>" }`	Expired, invalid, or tampered token.
`200`	`{ "status": false, "error": "You don't have permission to access this resource: API integration", "message": "..." }`	Plan does not include API integration.

Validation and business errors (handler)

When invoice creation fails inside the transaction, the API responds with HTTP 500 and:

{
  "status": false,
  "error": "<error message>"
}

Common error values returned from invoice creation:

Message	Typical cause
`Credits Expired!!!`	Invoice credit quota exhausted for the user.
`Business not found`	Token business is missing or inactive.
`Party detail is required`	Missing or empty `party_detail`.
`Mobile number or cash sale is required`	No valid `party_id`, and neither `mobile_no` nor `cash_sale` provided.
`Product name is required`	Line item missing product identity when required.
`Product sell price and gst is required`	New product creation without price or GST.
`Invoice number already exists`	Duplicate `invoice_number` for the firm.
`Received amount can not be greater than invoice total amount`	`receive_amount` exceeds calculated total.

Other failures (database, inventory, or unexpected errors) also return HTTP 500 with error set to the underlying message.

Behavior notes

Totals (taxable_amount, total_tax, total_discount, total_amount) are computed server-side from line items, additional charges, and optional invoice-level discount; you do not send final totals.
Default warehouse, invoice settings (prefix, sequence, notes, terms), and default signature are applied from the business configuration.
For most document types except quotations, purchase orders, and delivery challans, inventory and ledger entries are created automatically.
SMS/WhatsApp notifications may be sent according to business reminder settings when a mobile number is present.

​Endpoint

​Authentication

​Request body

​Top-level fields

​Party detail

​Product details

​Additional charges

​Example request

​Success response

​Error responses

​Authentication and plan (before handler)

​Validation and business errors (handler)

​Behavior notes

Endpoint

Authentication

Request body

Top-level fields

Party detail

Product details

Additional charges

Example request

Success response

Error responses

Authentication and plan (before handler)

Validation and business errors (handler)

Behavior notes