Create a Draft Invoice with the BSimple API

The BSimple invoice endpoint lets an authorised application create a draft invoice for an existing customer. A request can contain inventory-backed lines, free-form service lines, or both. BSimple validates the customer and item codes, applies configured pricing and GST rules, calculates totals, and returns the created invoice.

This endpoint creates a draft for the normal BSimple review and approval workflow. It does not approve, send, pay or delete an invoice.

Required access

Use an API key with the invoices:write scope. The customer must already exist in the BSimple account. Use customer_id or, where supported by the account workflow, customer_ref.

Endpoint

POST /api/v1/invoices/create

Send JSON with the API key in the X-API-Key header:

curl --fail --silent --request POST \
  --header "X-API-Key: ${BSIMPLE_API_KEY}" \
  --header 'Content-Type: application/json' \
  "${BSIMPLE_API_BASE}/invoices/create" \
  --data '{"customer_id":123,"lines":[{"item_code":"PRODUCT-001","quantity":2},{"description":"Installation labour","quantity":3,"unit_price":150.00}]}'

Request body

{
  "customer_id": 123,
  "lines": [
    {
      "item_code": "PRODUCT-001",
      "quantity": 2
    },
    {
      "description": "Installation labour",
      "quantity": 3,
      "unit_price": 150.00
    }
  ]
}

An inventory-backed line requires item_code and quantity. A service line requires description, quantity and unit_price. Do not send both line types' fields unless the request is intended to use the inventory item pricing behavior.

Pricing and GST

BSimple applies its configured pricing and tax behavior when it creates the draft. This can include the item's no_gst setting, customer-specific price overrides and the configured GST multiplier. The response includes calculated subtotal, tax and total values so the calling application can display or reconcile the result.

Do not calculate a second “official” total in the integration and assume it is authoritative. Treat BSimple's returned totals as the values that belong to the created draft.

Response

A successful response returns the created invoice and totals, including the invoice identifier, status, subtotal excluding GST, tax and total including GST. The exact response envelope follows the API documentation.

The current workflow creates a draft/pre-draft invoice for later review. It does not send the invoice to the customer or mark it as paid.

Validation failures

A request can fail if the customer does not exist, an item code is invalid, a required line field is missing, a quantity or price is invalid, or the key lacks invoices:write. Handle 401, 403, 404 and 422 responses separately so the integration does not repeatedly submit a request that needs correction.

Safe retry and duplicate prevention

Before adding automatic retries, confirm how your application identifies a previously created draft. A network timeout does not prove that the server did not create the invoice. Reconcile the account before repeating a timed-out write, and keep an application-side correlation record for each business operation.

The current public API does not document an idempotency-key mechanism. Do not claim that repeated POST requests are automatically deduplicated.

Create a Draft Invoice with the BSimple API