Bills

Supplier invoices. Creating one receives stock: each line creates or tops up a lot.

purchasing:readpurchasing:writehttps://public-api.nutrasoft.ca/v1

Links toSupplierssupplier_id Purchase orderspurchase_order_id Productslines[].product_id

The Bill object

idinteger
bill_datestringnullable
- date YYYY-MM-DD
bill_nointegernullable
billing_addressobject
ShowHide 5 fields of billing_address
- citystringnullable
- line1stringnullable
- line2stringnullable
- postal_codestringnullable
- statestringnullable
cancelled_atstringnullable
- date YYYY-MM-DD
companystringnullable
is_cancelledboolean
linesarray of objectsnullable
On a single bill and on writes; null on the list.
ShowHide 10 fields of lines
- idinteger
- costnumbernullable
  Per purchase unit. Requires cost:read.
- discount_ratenumbernullable
  Percent off this line. Requires cost:read.
- expiration_datestringnullable
  - UTC timestamp
- product_codestringnullable
- product_idintegernullable
- product_namestringnullable
- quantitynumbernullable
  Received, in the purchase unit.
- quantity_basenumbernullable
  Received, in the product's base unit.
- supplier_partnostringnullable
paid_amountnumbernullable
Requires cost:read.
purchase_order_idintegernullable

Show 7 more attributes

subtotalnumbernullable
Sum of the lines after line discounts, before tax. Requires cost:read; null means redacted, not zero.
supplier_idintegernullable
supplier_referencestringnullable
tax1booleannullable
Whether tax 1 applies to this document. Requires cost:read; null means redacted, not false.
tax1_ratenumbernullable
Tax 1 percentage, e.g. 5.0 for 5%. Requires cost:read.
tax2booleannullable
Whether tax 2 applies to this document. Requires cost:read; null means redacted, not false.
tax2_ratenumbernullable
Tax 2 percentage, e.g. 5.0 for 5%. Requires cost:read.

Operations

List bills

get/billspurchasing:read

What suppliers invoiced. Use search or the named filters, not both. Money fields require cost:read.

Query parameters

supplier_idintegernullable
- > 0
purchase_order_idintegernullable
- > 0
bill_date_fromstringnullable
- date YYYY-MM-DD
bill_date_tostringnullable
- date YYYY-MM-DD
searchstringnullable
Free-text match.
sortstringnullable
Comma-separated field:direction pairs, e.g. id:desc. Sortable: bill_date, bill_no, id. id is always added last, so paging is stable.
limitinteger
Rows to return. Maximum 200.
- >= 1
- <= 200
- default 50
offsetinteger
Rows to skip. Maximum 10000: to read further, narrow the filters or page with updated_since.
- >= 0
- <= 10000
- default 0

Returns

200 A page of Bill objects in data, with pagination.

Errors

400 401 403 429 500 503

GET /bills

curl "https://public-api.nutrasoft.ca/v1/bills?limit=50" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "bill_date": "2026-09-10",
      "bill_no": 10,
      "billing_address": {
        "city": "Montreal",
        "line1": "123 Example Street",
        "line2": "Suite 200",
        "postal_code": "H4S 2C1",
        "state": "QC"
      },
      "cancelled_at": "2026-09-10",
      "company": "Example Foods Inc.",
      "is_cancelled": false,
      "lines": null,
      "paid_amount": 12.5,
      "purchase_order_id": 123,
      "subtotal": 12.5,
      "supplier_id": 123,
      "supplier_reference": "INV-58213",
      "tax1": false,
      "tax1_rate": 12.5,
      "tax2": false,
      "tax2_rate": 12.5
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve a bill

get/bills/{bill_id}purchasing:read

Path parameters

bill_idintegerrequired
The bill's id.
- > 0

Returns

200 One Bill object in data.

Errors

400 401 403 404 429 500 503

GET /bills/{bill_id}

curl "https://public-api.nutrasoft.ca/v1/bills/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "bill_date": "2026-09-10",
    "bill_no": 10,
    "billing_address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "cancelled_at": "2026-09-10",
    "company": "Example Foods Inc.",
    "is_cancelled": false,
    "lines": [
      {
        "id": 123,
        "cost": 12.5,
        "discount_rate": 12.5,
        "expiration_date": "2026-09-10T14:30:00Z",
        "product_code": "SAMPLE-01",
        "product_id": 123,
        "product_name": "Sample name",
        "quantity": 12.5,
        "quantity_base": 12.5,
        "supplier_partno": "string"
      }
    ],
    "paid_amount": 12.5,
    "purchase_order_id": 123,
    "subtotal": 12.5,
    "supplier_id": 123,
    "supplier_reference": "INV-58213",
    "tax1": false,
    "tax1_rate": 12.5,
    "tax2": false,
    "tax2_rate": 12.5
  }
}

Create a bill

post/billspurchasing:write· idempotent with Idempotency-Key

Receives stock. Each line creates a lot, or tops up the lot with that number for that product at that location, and writes one PURCHASE_ENTRY stock movement. Unless your account costs manually, product costs are recalculated. quantity and cost are in the purchase unit; lots are in base units.

Idempotent on Idempotency-Key: a retry with the same key returns the bill the first call created, with status 200, and receives nothing twice. Reusing a key with a different body is a 409.

A lot number that exists for the product and location with a different expiry is a 409; with the same expiry the lot is topped up.

Headers

Idempotency-Keystringnullable
Your own unique string for this bill, up to 200 characters. Reusing it returns the bill it created the first time.
- max 200 chars

Request body

bill_datestringrequired
The date on the supplier's invoice.
- date YYYY-MM-DD
linesarray of objectsrequired
At least 1 line and at most 1000, for at most 200 different products. Each line receives stock.
- 1 to 1000 items
ShowHide 8 fields of lines
- lot_numberstringrequired
  The supplier's lot code.
  - min 1 chars
  - max 100 chars
- product_idintegerrequired
  A product in your account.
  - > 0
- quantitynumberrequired
  In the product's purchase unit.
  - > 0
- costnumbernullable
  Per purchase unit.
  - >= 0
- discount_ratenumbernullable
  - >= 0
  - <= 100
- expiration_datestringnullable
  Refused with 409 when the lot exists with a different expiry.
  - date YYYY-MM-DD
- location_idintegernullable
  Where the stock lands: one of your warehouses or a location in one.
  - > 0
- supplier_partnostringnullable
  - max 100 chars
supplier_idintegerrequired
- > 0
notesstringnullable
- max 2000 chars
purchase_order_idintegernullable
Links the bill to one of your orders, without changing its status.
- > 0
supplier_referencestringnullable
Usually the supplier's own invoice number.
- max 255 chars

Returns

201 One Bill object in data.

Errors

400 401 403 409 429 500 503

POST /bills

curl -X POST "https://public-api.nutrasoft.ca/v1/bills" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c6a52-8d0e-4b7a-9c2f-5e8d1b4a7c90" \
  -d '{
  "bill_date": "2026-09-10",
  "lines": [
    {
      "lot_number": "LOT-2026-0142",
      "product_id": 123,
      "quantity": 12.5
    }
  ],
  "supplier_id": 123
}'

Response201

{
  "data": {
    "id": 123,
    "bill_date": "2026-09-10",
    "bill_no": 10,
    "billing_address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "cancelled_at": "2026-09-10",
    "company": "Example Foods Inc.",
    "is_cancelled": false,
    "lines": [
      {
        "id": 123,
        "cost": 12.5,
        "discount_rate": 12.5,
        "expiration_date": "2026-09-10T14:30:00Z",
        "product_code": "SAMPLE-01",
        "product_id": 123,
        "product_name": "Sample name",
        "quantity": 12.5,
        "quantity_base": 12.5,
        "supplier_partno": "string"
      }
    ],
    "paid_amount": 12.5,
    "purchase_order_id": 123,
    "subtotal": 12.5,
    "supplier_id": 123,
    "supplier_reference": "INV-58213",
    "tax1": false,
    "tax1_rate": 12.5,
    "tax2": false,
    "tax2_rate": 12.5
  }
}