Bills and vendors

recurring bills

List

GET/v1/recurring-bills

List recurring-bill schedules.

Scope

bills:read

Effect

Read only

MCP tool

list_recurring_bills

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/recurring-bills" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

recurring bills

Create

POST/v1/recurring-bills

Create a schedule that drafts a bill for a vendor on a frequency. Each occurrence is a DRAFT bill that a person opens; nothing is paid or approved. Totals are derived from the lines. A start date in the past answers 409 MISSED_OCCURRENCES with the count until missed is skip or issue.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

create_recurring_bill

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/recurring-bills" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"vendorId":"<vendorId>","frequency":"weekly","startDate":"<startDate>"}'

recurring bills

Get

GET/v1/recurring-bills/{recurringBillId}

One recurring-bill schedule.

Scope

bills:read

Effect

Read only

MCP tool

get_recurring_bill

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/recurring-bills/{recurringBillId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

recurring bills

Pause

POST/v1/recurring-bills/{recurringBillId}/pause

Pause a recurring-bill schedule: no further bill is drafted until a person resumes it in the console.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

pause_recurring_bill

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/recurring-bills/{recurringBillId}/pause" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

bills

List

GET/v1/bills

List bills, newest first. A discarded draft is left out unless discarded=true.

Scope

bills:read

Effect

Read only

MCP tool

list_bills

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/bills" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

bills

Create

POST/v1/bills

Create a bill as a DRAFT. Totals are derived server-side from the lines, never taken from input.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

create_bill

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"vendorName":"<vendorName>","currency":"USD"}'

bills

Get

GET/v1/bills/{billId}

One bill with its lines and what is still due.

Scope

bills:read

Effect

Read only

MCP tool

get_bill

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/bills/{billId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

bills

Update

PATCH/v1/bills/{billId}

Update a bill. A DRAFT takes vendor, dates, reference, category, notes and lines (totals re-derived); an opened bill takes notes and category only; a void bill nothing.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

update_bill

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/bills/{billId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

bills

Payments

GET/v1/bills/{billId}/payments

The payments recorded against one bill, as ledger entries (entryId is what void_bill_payment takes), oldest first.

Scope

bills:read

Effect

Read only

MCP tool

list_bill_payments

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/bills/{billId}/payments" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

vendors

List

GET/v1/vendors

List vendors, newest first (contact details masked unless contacts:read).

Scope

bills:read

Effect

Read only

MCP tool

list_vendors

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/vendors" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

vendors

Create

POST/v1/vendors

Create a vendor. Contact details are stored as given; nothing is verified or contacted.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

create_vendor

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/vendors" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

vendors

Get

GET/v1/vendors/{vendorId}

One vendor.

Scope

bills:read

Effect

Read only

MCP tool

get_vendor

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/vendors/{vendorId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

vendors

Update

PATCH/v1/vendors/{vendorId}

Update a vendor’s editable fields.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

update_vendor

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/vendors/{vendorId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

vendors

Archive

POST/v1/vendors/{vendorId}/archive

Archive or restore a vendor. Never deleted: bills point at it.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

archive_vendor

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/vendors/{vendorId}/archive" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

bills

Set allocations

POST/v1/bills/{billId}/allocations

Charge a DRAFT bill to work records: the list replaces the one stored, and expectedUpdatedAt (the bill updatedAt you read) is required. Each amount is in the bill currency; together they never exceed the bill total, and what is left stays unallocated.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

allocate_bill_to_jobs

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills/{billId}/allocations" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"expectedUpdatedAt":"<expectedUpdatedAt>"}'

bills

Discard

POST/v1/bills/{billId}/discard

Discard a DRAFT bill. Refused once opened, or while an action on it is pending.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

discard_draft_bill

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills/{billId}/discard" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

bills

Submit approval

POST/v1/bills/{billId}/submit-approval

Submit a DRAFT bill for approval. If the workspace policy covers its total, an approver must approve it before it can be opened; otherwise it answers that none is needed.

Scope

bills:write

Effect

Writes a draft or record

MCP tool

submit_bill_for_approval

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills/{billId}/submit-approval" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

bills

Approve

POST/v1/bills/{billId}/approve

Approve a bill that is waiting for approval, as the person whose API key this is. The person who entered the bill cannot (unless nobody else could); the last required approval opens the bill.

Scope

bills:approve

Effect

Writes a draft or record

MCP tool

None — REST and API keys only

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills/{billId}/approve" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

bills

Reject

POST/v1/bills/{billId}/reject

Reject a bill that is waiting for approval, with a reason. It goes back to a draft the submitter can edit and submit again.

Scope

bills:approve

Effect

Writes a draft or record

MCP tool

None — REST and API keys only

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/bills/{billId}/reject" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"<reason>"}'

Object

RecurringBill

A schedule that drafts bills: rent, software, insurance. Each occurrence is a DRAFT bill the hourly runner makes under a deterministic id; nothing is paid and nothing is approved by the schedule. With `openAutomatically` the runner also opens the draft through the bill-opening rules.

Object

Bill

A payable: money the tenant owes a vendor. Deliberately NOT an invoice with the sign flipped — a bill has no public link, no metering, no gateway path, and its lines are not rebillable without an explicit expense record.

Object

Vendor

Someone the tenant pays. Staff data written through the rules, never an identity: no contact key, no identity link, no verification. A bill copies the vendor's name and email into its own snapshot, so editing a vendor never rewrites a bill. Archived, never deleted.