BillsCreate a bill

Create a bill

POST/firm-partners/workspace/bills

Creates a new vendor bill (draft by default, or approved for migrations).

Required: exactly one of vendorUuid OR inline vendor object, date, dueDate (bills only), and lineItems with categoryAccountUuid, quantity, and price. Optional approvalStatus (draft | approved) and billType. Inline vendors are echoed on the response as _partnerInlineCreated.

Some fields work differently in US and NZ workspaces

Showing US sales tax and NZ GST rules.

HMAC signature only

Headers

count-workspace-iduuidrequired

UUID of the client workspace to act on. It must be one of your firm's client workspaces (or the firm's own workspace) and within the API key's client workspaces.

Request body

vendorUuiduuid

Existing vendor UUID from the Vendors API. Mutually exclusive with vendor.

vendorobject

Inline vendor to create when vendorUuid is omitted.

namestring

Vendor display name (or use vendor field alias).

emailstring

Optional vendor email.

datedaterequired

Bill date (ISO, YYYY-MM-DD).

dueDatedate

Due date (ISO, YYYY-MM-DD). Send it on every bill — a bill without one is filed as a draft. Omit it on a vendor memo; the server sets its due date.

billTypeenum

Defaults to bill. `vendor_memo` creates a vendor credit instead; it is numbered automatically and its billNumber and dueDate are ignored.

One of: bill, vendor_memo

lineItemsarrayrequired

Expense lines on the bill.

categoryAccountUuiduuidrequired

Expense account UUID from Chart of Accounts.

descriptionstring

Line description.

quantitynumberrequired

Quantity.

pricenumberrequired

Unit price.

projectUuiduuid

Optional project UUID on the line.

customerUuiduuid

Optional customer UUID for billable expenses.

taxUuiduuid

Tax code UUID from List tax codes, or null to clear it.

  • US· Sales taxIgnored; bills carry no tax.
  • NZ· GSTThe line's GST code: `15% GST on Expenses`, `No GST`, or `GST on Imports` (GST on Imports account only).
tagUuidsarray

Tag UUIDs for this line only. They code the line's expense and tax postings; bill-level `tagUuids` apply to every posting.

fixedAssetAssignmentobject

Names the fixed asset this line's cost belongs to, instead of the draft COUNT would create. Only on a positive line of a bill (not a vendor credit) categorized to a Fixed Assets account. Applied when the bill is approved, or at once when it is saved approved; until then the line keeps it.

actionenumrequired

Put the line on an existing asset, or start a new draft.

One of: assign_existing, create_new

fixedAssetUuiduuid

For `assign_existing`: the asset UUID from List fixed assets.

fixedAssetTypeUuiduuid

For `create_new`: the type UUID from List fixed asset types.

assetNamestring

For `create_new`: the new draft's name. Defaults to the line description.

billNumberstring

Custom bill number. Auto-assigned when omitted.

purchaseOrderNumberstring

Purchase order reference.

notesstring

Free-text notes.

currencystring

ISO 4217 currency. Defaults to workspace currency.

bookingExchangeRatenumber

Your own rate from the document currency to the workspace currency. Only used together with `exchangeRateSource: "user"`; otherwise COUNT looks up the rate itself.

exchangeRateSourcestring

Send `user` with `bookingExchangeRate` to fix the rate. On update, `null` goes back to the rate COUNT looks up for the document date.

tagUuidsarray

Tag UUIDs from the Tags API, applied to every posting of the bill. Use `lineItems[].tagUuids` to code individual lines.

projectUuiduuid

Bill-level project UUID.

approvalStatusenum

Draft (default) or approved — approved posts A/P journals immediately (migration use case).

One of: draft, approved

attachmentsarray

Supporting documents to store on the bill, by public URL or inline content. Each file is up to 20 MB. An empty list or an omitted field adds nothing. Up to 10 entries; every file is downloaded or decoded and virus-scanned before anything is saved, so one bad file fails the whole request.

urlstring

A public http(s) URL. COUNT downloads the file and stores its own copy, so the link only has to work at the moment you call. Send either `url` or `contentBase64`, not both.

fileNamestring

Required with `contentBase64`. The file name, including its extension.

contentBase64string

The file's bytes, base64-encoded (a `data:...;base64,` prefix is accepted). At most 10 MB once decoded, or the route's own cap where that is lower.

contentTypestring

Optional MIME type, e.g. `application/pdf`. Worked out from `fileName` when omitted.

titlestring

Optional display title. Defaults to the file name.

Responses

201Bill created in draft.
400Validation failed — missing required fields or invalid UUID references.
401Missing signing headers, an invalid HMAC signature, or a timestamp more than 5 minutes off. Troubleshoot
403The key is inactive or its scope does not allow this request, the workspace is not managed by your firm or is outside the key's client workspaces, the workspace has no active subscription, or it is portal-only and the route needs bookkeeping. Troubleshoot
404No workspace exists with the `count-workspace-id` UUID.
429Rate limit exceeded (100 requests per minute per firm user of each app, or 10,000 per minute per app). Troubleshoot
POSThttps://api.getcount.com/firm-partners/workspace/bills
Request
import crypto from 'node:crypto';

const BASE_URL = 'https://api.getcount.com';
const CLIENT_ID = process.env.COUNT_CLIENT_ID;
const CLIENT_SECRET = process.env.COUNT_CLIENT_SECRET;

const method = 'POST';
const signingPath = '/workspace/bills';
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = {
  "vendorUuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "date": "2026-01-15",
  "dueDate": "2026-02-15",
  "lineItems": [
    {
      "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "description": "Office supplies",
      "quantity": 1,
      "price": 250
    }
  ],
  "notes": "Q1 office supplies"
};
const bodyString = JSON.stringify(body);

const bodyHash = crypto.createHash('sha256').update(bodyString).digest('hex');
const baseString = `${method}:${signingPath}:${timestamp}:${bodyHash}`;
const signature = crypto.createHmac('sha256', CLIENT_SECRET).update(baseString).digest('hex');

const response = await fetch(`${BASE_URL}/firm-partners/workspace/bills`, {
  method,
  headers: {
    'x-client-id': CLIENT_ID,
    'x-timestamp': timestamp,
    'x-signature': signature,
    'Content-Type': 'application/json',
    'count-workspace-id': '5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716',
  },
  body: bodyString,
});

console.log(await response.json());
Response · 201
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "billNumber": "BILL-1043",
  "billType": "bill",
  "date": "2026-01-15",
  "dueDate": "2026-02-15",
  "currency": "USD",
  "approvalStatus": "draft",
  "status": "draft",
  "total": 250,
  "paidAmount": 0,
  "amountDue": 250,
  "notes": "Office supplies for Q1",
  "purchaseOrderNumber": null,
  "isDeleted": false,
  "vendor": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Office Depot",
    "email": "ap@officedepot.example"
  },
  "lineItems": [
    {
      "id": "a4b5c6d7-e8f9-0123-abcd-456789012345",
      "description": "Office supplies",
      "quantity": 1,
      "price": 250,
      "total": 250,
      "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  ],
  "transactions": [],
  "appliedVendorMemos": [],
  "tagUuids": [],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-28T14:22:30.000Z"
}