Bills

List, create, update, and delete bills; nested bill items on the parent resource; optional contact and project hydration on get.

   
SDK service client.Bills (BillService)
FreeAgent docs dev.freeagent.com/docs/bills
Sample app /bills (list), /bills/detail (CRUD)

Pagination patterns: see Pagination. Contact, project, and category links: see Linked resources. Purchases cluster patterns: see Purchases entity map.

Nested attachment on bill responses may omit thumbnail URLs and expires_at. For the full attachment payload, call Attachments (client.Attachments.GetAttachmentAsync) using the attachment ID from the nested url.

Sales tax on bill items

Per Sales tax and VAT: on each BillItem, use PurchaseSalesTaxRate for SalesTaxRate (Auto or a percentage), optional ManualSalesTaxAmount, and SalesTaxStatus (BillSalesTaxStatus). SalesTaxValue is calculated by FreeAgent on read.

Methods

ListAsync

Task<PaginatedResponse<Bill>> ListAsync(
    int page = 1,
    int perPage = 25,
    string? view = null,
    DateOnly? fromDate = null,
    DateOnly? toDate = null,
    DateTimeOffset? updatedSince = null,
    ContactReference? contact = null,
    long? contactId = null,
    ProjectReference? project = null,
    long? projectId = null,
    bool? nestedBillItems = null,
    CancellationToken cancellationToken = default)
Parameter Type Required Default Wire
page int No 1 page
perPage int No 25 per_page (max 100)
view string? No null view
fromDate DateOnly? No null from_date
toDate DateOnly? No null to_date
updatedSince DateTimeOffset? No null updated_since
contact ContactReference? No null contact (URI)
contactId long? No null contact (URI from client.Urls.Contact(id))
project ProjectReference? No null project (URI)
projectId long? No null project (URI from client.Urls.Project(id))
nestedBillItems bool? No null nested_bill_items
cancellationToken CancellationToken No default -

HTTP: GET /v2/bills

Client validation: page ≥ 1; perPage between 1 and 100; supply contact or contactId, not both; supply project or projectId, not both.

Sample:

var page = await client.Bills.ListAsync(
    view: BillView.Open,
    contactId: 42,
    nestedBillItems: true);

ListAutoPagingAsync

IAsyncEnumerable<Bill> ListAutoPagingAsync(...)

Same query parameters as ListAsync except page.


GetBillAsync

Task<Bill> GetBillAsync(long billId, CancellationToken cancellationToken = default)

Task<Bill> GetBillAsync(
    long billId,
    BillGetOptions? options,
    CancellationToken cancellationToken = default)

HTTP: GET /v2/bills/:id

When options.IncludeContact, options.IncludeProject, options.IncludeRebillToProject, or options.IncludeRebilledOnInvoice is true, the SDK fetches linked resources when the response contains only URIs. IncludeRebilledOnInvoice applies when rebilled_on_invoice_item is an invoice URI (not an invoice item URI).


CreateBillAsync

Task<Bill> CreateBillAsync(Bill bill, CancellationToken cancellationToken = default)

HTTP: POST /v2/bills

Required on create: ContactId, DatedOn, and at least one line item with Description, CategoryNominalCode, and value fields appropriate to your account.


UpdateBillAsync

Task<Bill> UpdateBillAsync(
    long billId,
    Bill bill,
    BillUpdateOptions? options = null,
    CancellationToken cancellationToken = default)

HTTP: PUT /v2/bills/:id

Update existing line items using the bill item resource URL (set BillItem.Url or rely on ItemId parsed from a prior GET). Delete line items with a bill item URL and Destroy = 1. Pass new BillUpdateOptions { OmitLineItems = true } to update scalar fields without sending line items.


DeleteBillAsync

Task DeleteBillAsync(long billId, CancellationToken cancellationToken = default)

HTTP: DELETE /v2/bills/:id


List filters

view (BillView)

Constant Wire value
BillView.All all
BillView.Open open
BillView.Overdue overdue
BillView.OpenOrOverdue open_or_overdue
BillView.OpenOrOverduePayments open_or_overdue_payments
BillView.OpenOrOverdueRefunds open_or_overdue_refunds
BillView.Paid paid
BillView.Recurring recurring
BillView.HirePurchase hire_purchase
BillView.Cis cis

BillGetOptions

Property Type Purpose
IncludeContact bool Fetch contact when only a URI is returned
IncludeProject bool Fetch project when only a URI is returned

BillUpdateOptions

Property Type Purpose
OmitLineItems bool Exclude line items from the update payload
OmitContact bool Exclude the contact link from the update payload
OmitProject bool Exclude the project link from the update payload
OmitRebillToProject bool Exclude the rebill target project link from the update payload

Bill model

Key properties:

Property Type Wire name Notes
Reference string? reference  
Status BillStatus? status Read-only payment status
DatedOn DateOnly? dated_on Required on create
DueOn DateOnly? due_on  
ContactId long? contact Required on create
ProjectId long? project Optional project link
IsPaidByHirePurchase bool? is_paid_by_hire_purchase Hire purchase flag
BillItems List<BillItem>? bill_items Nested line items
ItemId long? (from url on line items) Parsed from bill item URL
CategoryNominalCode string? category (line items) Category link on line items
TotalValue decimal? total_value Read-only on bill; writable on line items
Url string url  

Errors

Failures throw FreeAgentApiException.


Copyright © Mark Heydon. Distributed under the MIT licence.

This site uses Just the Docs, a documentation theme for Jekyll.