Create a new Expense

Creates a new expense from scratch

View as Markdown

POST /v1/expense

Needs an API key with the write scope.

Parameters

description string Required

Description of the expense. This will also be its title in the Nuvio Platform.
expenseDate string Required

The date of the expense. Should be formatted in YYYY-MM-DD format
dueDate string Required

Due date of the payment for this expense. Should be formatted in YYYY-MM-DD format.
items array of objects Required

List of the items that are linked to this expense.
Show child parameters Hide child parameters
- itemDetail string Required
  
  Description of the item. Should be a string.
- productId string
  
  32-character unique ID of the product. If you don't know the ID, you can also provide productCode instead of this field. If both of them are provided, productId will be used only.
- productCode string
  
  User-generated custom unique code of the specific product. If productId is also provided, it will override this field.
- quantity integer
  
  Quantity of the sold items. It should be a positive integer.
- itemTaxes array of strings
  
  A list of the taxes to be applied to the related line item. Provide a list of taxes with their 32-character unique ID.
- unitPrice number
  
  Net Amount of a single product sold. Should be a positive decimal number with 2 decimal points. eg. 32.43

More parameters

referenceNumber string

Invoice or receipt number of the received expense, formatted in string. Accepts alpha numeric characters and '-' symbol.
currency string

3-letter currency code. You can find all the available currencies here.
projectId string

32-character unique ID of the related project. If you don't know the ID, you can also provide projectCode instead of this field. If both of them are provided projectId will be used only.
projectCode string

User-generated custom code of the related project. If projectId` is also provided, it will override this field.
supplierId string

32-character unique ID of the supplier. If you don't know the ID, you can also provide supplierCode instead of this field. If both of them are provided, supplierId will be used only.
supplierCode string

User-generated custom unique code of the specific supplier. If supplierId is also provided, it will override this field.
tags array of strings

List of the tags that are related to this expense. Provide a list of tags with their 32-character unique ID.
exchangeRate number

If currency is different than your company's functional currency, this will be the exchange rate that Nuvio will use while converting the amounts of this expense to company's functional currency. Should be number with 4 decimal points. eg. 32.4325

Returns

The created expense.

401: No usable Authorization: Bearer {token} header (1002).
403: The access token is unknown, or lacks the scope this route needs (1001).

POST /v1/expense

curl -X POST https://api.nuvio.io/v1/expense \
  -H "Authorization: Bearer $NUVIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Office supplies",
    "expenseDate": "2026-11-05",
    "dueDate": "2026-11-05",
    "items": [
      {
        "itemDetail": "Office supplies"
      }
    ]
  }'

const response = await fetch('https://api.nuvio.io/v1/expense', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NUVIO_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": "Office supplies",
    "expenseDate": "2026-11-05",
    "dueDate": "2026-11-05",
    "items": [
      {
        "itemDetail": "Office supplies"
      }
    ]
  }),
});
const { data } = await response.json();

import os
import requests

response = requests.post(
    "https://api.nuvio.io/v1/expense",
    headers={"Authorization": f"Bearer {os.environ['NUVIO_API_TOKEN']}"},
    json={
        "description": "Office supplies",
        "expenseDate": "2026-11-05",
        "dueDate": "2026-11-05",
        "items": [
            {
                "itemDetail": "Office supplies",
            },
        ],
    },
)
data = response.json()["data"]

Response

{
  "success": true,
  "errors": null,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "referenceNumber": "INV-2026-0042",
    "paymentStatus": "Pending",
    "description": "Office supplies",
    "dueDate": "2026-11-05",
    "expenseDate": "2026-11-05",
    "currency": "USD",
    "exchangeRate": 1,
    "project": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Acme Supplies",
      "projectCode": "ACME-01"
    },
    "supplier": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Acme Supplies",
      "entityCode": "ACME-01"
    },
    "tags": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Acme Supplies"
      }
    ],
    "subTotal": 100,
    "totalTax": 100,
    "totalAmount": 100,
    "remainingAmount": 100,
    "items": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "itemDetail": "Office supplies",
        "productCode": "ACME-01",
        "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "productName": "Acme Supplies",
        "quantity": 1,
        "unitPrice": 100,
        "totalTaxes": 100,
        "totalAmount": 100,
        "itemTaxes": [
          {
            "taxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "taxName": "Acme Supplies",
            "taxAmount": 100
          }
        ]
      }
    ],
    "matchedPayments": [
      {
        "bankAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "bankAccountName": "Acme Supplies",
        "transactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "amount": 100,
        "currency": "USD",
        "description": "Office supplies",
        "transactionDate": "2026-11-05"
      }
    ]
  }
}