Create a bill
/firm-partners/workspace/billsCreates 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.
Headers
count-workspace-iduuidrequiredUUID 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
vendorUuiduuidExisting vendor UUID from the Vendors API. Mutually exclusive with vendor.
vendorobjectInline vendor to create when vendorUuid is omitted.
namestringVendor display name (or use vendor field alias).
emailstringOptional vendor email.
datedaterequiredBill date (ISO, YYYY-MM-DD).
dueDatedateDue 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.
billTypeenumDefaults 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
lineItemsarrayrequiredExpense lines on the bill.
categoryAccountUuiduuidrequiredExpense account UUID from Chart of Accounts.
descriptionstringLine description.
quantitynumberrequiredQuantity.
pricenumberrequiredUnit price.
projectUuiduuidOptional project UUID on the line.
customerUuiduuidOptional customer UUID for billable expenses.
taxUuiduuidTax 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).
tagUuidsarrayTag UUIDs for this line only. They code the line's expense and tax postings; bill-level `tagUuids` apply to every posting.
fixedAssetAssignmentobjectNames 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.
actionenumrequiredPut the line on an existing asset, or start a new draft.
One of: assign_existing, create_new
fixedAssetUuiduuidFor `assign_existing`: the asset UUID from List fixed assets.
fixedAssetTypeUuiduuidFor `create_new`: the type UUID from List fixed asset types.
assetNamestringFor `create_new`: the new draft's name. Defaults to the line description.
billNumberstringCustom bill number. Auto-assigned when omitted.
purchaseOrderNumberstringPurchase order reference.
notesstringFree-text notes.
currencystringISO 4217 currency. Defaults to workspace currency.
bookingExchangeRatenumberYour own rate from the document currency to the workspace currency. Only used together with `exchangeRateSource: "user"`; otherwise COUNT looks up the rate itself.
exchangeRateSourcestringSend `user` with `bookingExchangeRate` to fix the rate. On update, `null` goes back to the rate COUNT looks up for the document date.
tagUuidsarrayTag UUIDs from the Tags API, applied to every posting of the bill. Use `lineItems[].tagUuids` to code individual lines.
projectUuiduuidBill-level project UUID.
approvalStatusenumDraft (default) or approved — approved posts A/P journals immediately (migration use case).
One of: draft, approved
attachmentsarraySupporting 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.
urlstringA 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.
fileNamestringRequired with `contentBase64`. The file name, including its extension.
contentBase64stringThe 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.
contentTypestringOptional MIME type, e.g. `application/pdf`. Worked out from `fileName` when omitted.
titlestringOptional 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. Troubleshoot403The 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. Troubleshoot404No 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). Troubleshoothttps://api.getcount.com/firm-partners/workspace/billsimport 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());{
"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"
}