Bills
refer to documents or records that detail a transaction where one party requests payment from another for goods or services provided.
Get All Bills
To get all bills, make a GET request to the /api/v3/bills/awaiting endpoint. Sample request using axios:
jsconst response = await axios.get("/api/v3/bills/awaiting?page=<page_number>");
Where <page_number> is the page number of the list
Sample Response object:
json{
"all_": {
"current_page": 1,
"data": [
{
"id": 61816,
"bill_id": "BILL362",
"user_id": 1,
"business_id": 1,
"purchase_date": "2024-10-15",
"due_date": "2024-10-15",
"payment_account": null,
"supplier_id": 9167,
"gross_amount": 5.58,
"discount_amount": 0,
"discount_percentage": "0.0",
"amount_due": 5.58,
"paid_status": "Paid",
"amount_paid": 5.58,
"date_paid": "2024-10-23",
"balance": 0,
"note": "<p>This is a test bill<\/p>",
"created_at": "2024-10-15T13:15:48.000000Z",
"updated_at": "2024-10-23T16:11:21.000000Z",
"tag": "",
"deleted_at": null,
"base_currency": "GHS",
"fx_currency": "GHS",
"fx_rate": 1,
"fx_amount": 5.58,
"enc_id": "<ENC_ID>",
"total_taxAmount": null,
"amount_left": 0,
"supplier": {
"id": 9167,
"owner_id": 1,
"business_id": 1,
"supplier_name": "Aaa",
"supplier_address": "",
"supplier_phone": "",
"supplier_location": "",
"supplier_email": "",
"created_at": "2023-03-23T14:26:17.000000Z",
"updated_at": "2024-11-01T09:23:28.000000Z",
"bank_code": "",
"account_number": null,
"account_name": null,
"bank_id": "",
"account_id": 570544,
"archived": false,
"transactions": [],
"unformated_balance": 1067.32,
"balance": "1,067.32",
"total_debit": "59,739.32",
"total_credit": "60,806.64",
"has_payment_account": false
},
"attachments": [],
"online_payments": [],
"withholding": [],
"payment_history": [
{
"id": 51671,
"bill_id": 61816,
"payment_accountID": 3,
"amount": 5.58,
"date_paid": "2024-10-23",
"created_at": "2024-10-23T16:11:21.000000Z",
"updated_at": "2024-10-23T16:11:21.000000Z",
"fx_currency": "GHS",
"base_currency": "GHS",
"rate": 1,
"fx_amount": 5.58,
"account": {
"id": 3,
"account_name": "SC new",
"type_id": 3,
"subtype_id": 3,
"code": "N\/A",
"description": "FANBASE ADB Account",
"user_id": 1,
"business_id": 1,
"holder_id": 0,
"created_at": "2020-03-05 01:42:57",
"updated_at": "2024-05-21 11:00:41",
"currency": "GHS",
"archived": 0,
"live_account_id": null,
"live_balance": "0",
"live_bank_account_data": null
}
}
"withholding": [
{
"id": 348,
"payable_accountID": 109829,
"withholding_accountID": 4996,
"bill_id": 9884,
"amount": 23,
"entry_date": "2022-05-31",
"created_at": "2022-05-29T23:44:03.000000Z",
"updated_at": "2022-05-29T23:44:03.000000Z"
}
],
"payment_history": [
{
"id": 7955,
"bill_id": 9884,
"payment_accountID": 24386,
"amount": 555.63,
"date_paid": "2022-05-31",
"created_at": "2022-05-29T23:46:05.000000Z",
"updated_at": "2022-05-29T23:46:05.000000Z",
"fx_currency": "GHS",
"base_currency": "GHS",
"rate": 1,
"fx_amount": 555.63,
"account": {
"id": 24386,
"account_name": "Fidelity Cedi Account",
"type_id": 3,
"subtype_id": 3,
"code": "10050",
"description": "",
"user_id": 1,
"business_id": 1,
"holder_id": null,
"created_at": "2020-09-11 12:43:53",
"updated_at": "2024-03-11 13:31:25",
"currency": "GHS",
"archived": 1,
"live_account_id": null,
"live_balance": "0",
"live_bank_account_data": null
}
}
]
}
],
"first_page_url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=2",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=1",
"label": "1",
"active": true
},
{
"url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=2",
"label": "2",
"active": false
},
{
"url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=2",
"label": "Next »",
"active": false
}
],
"next_page_url": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all?page=2",
"path": "https:\/\/web.builtaccounting.com\/api\/v3\/bills/list/all",
"per_page": 50,
"prev_page_url": null,
"to": 50,
"total": 97
}
}
Get Awaiting
To get awaiting , make a GET request to the /api/v3/bills/awaiting endpoint. Sample request using axios:
jsconst response = axios.get("/api/v3/bills/awaiting");
The Response object returned is the same as the one for getting all
Get Overdue
To get overdue , make a GET request to the /api/v3/bills/awaiting endpoint. Sample request using axios:
jsconst response = await axios.get(`/api/v3/bills/awaiting`);
The Response object returned is the same as the one for getting all
Get Paid
To get paid , make a GET request to the /api/v3/bills/awaiting endpoint. Sample request using axios:
jsconst response = await axios.get("/api/v3/bills/awaiting");
The Response object returned is the same as the one for getting all -->
Get Summaries
This returns an Object containing the summary information of the various lists(All , paid , awaiting , overdue )
To get summaries, make a GET request to the /api/v3/bills/:id endpoint. Sample request using axios:
jsconst response = await axios.get("/api/v3/bills/:id");
Sample Response object:
json{
"awaiting": { "count": 0, "total_amount": 0 },
"all": { "count": 219, "total_amount": 525698267.13 },
"overdue": { "count": 122, "total_amount": 508511982.34 },
"paid": { "count": 97, "total_amount": 17125349.94 }
}
Creating a Bill
To create a bill, you will need to at least add or select a supplier and an item to create the bill.
Make a POST request to /api/v3/bills endpoint to create a bill. Sample request using axios:
jsconst response = await axios.post(
"/api/v3/bills",
{
supplier_id: 456, // The ID of the supplier
purchase_date: "2024-01-15", // The date of purchase
due_date: "2024-02-15", // Due date for payment to the supplier
gross_amount: 2000.0, // Total amount to pay before discounts
discount_amount: 100.0, // Discount applied to the order
amount_due: 1900.0, // Amount due after discount
items: [
// List of items in the purchase order
{
product_id: 101, // ID of the product
description: "Office supplies", // Description of the item
tax_id: 5, // Tax ID applied to the item
rawUnit_price: 100.0, // Raw unit price without tax
invoice_amount: 1000.0, // Total amount on invoice for this item
invoice_quantity: 10, // Quantity of items on the invoice
unit_cost: 95.0, // Cost per unit after adjustments
taxes: 15.0, // Tax rate or amount
purchase_accountID: 300, // Purchase account ID
tax_amount: 150.0, // Total tax amount on item
tax_ids: [5, 6], // List of tax IDs applied
track_inventory: true, // Whether the item is tracked in inventory
supplier_tax: 5, // Supplier-specific tax
name: "Paper", // Name of the item
description: "A4 printing paper", // Description for the line item
quantity: 10, // Quantity ordered
temp_taxAmount: 15.0, // Temporary tax amount
total_tax_rate: 5, // Total tax rate applied to item
item: "Office Paper", // Item name or SKU
},
],
note: "Payment due within 30 days", // Note on the order
credit: 50.0, // Credit amount for the purchase
payment_accountID: 101, // Account ID for payment
tag: "Office Supplies", // Tag for the purchase item
fx_rate: 5.7, // Foreign exchange rate
fx_amount: 10830.0, // Amount in foreign currency
fx_currency: "GHS", // Foreign currency used for the purchase
},
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
},
);
Here is an example response received after successfully creating a bill:
json{
{
"id": 62907,
"bill_id": "BILL363",
"user_id": 1,
"business_id": 1,
"purchase_date": "2024-11-04",
"due_date": "2024-11-04",
"payment_account": null,
"supplier_id": 1573,
"gross_amount": 130,
"discount_amount": 0,
"discount_percentage": "0.0",
"amount_due": 130,
"paid_status": "Not Paid",
"amount_paid": 0,
"date_paid": null,
"balance": 0,
"note": "",
"created_at": "2024-11-04T17:06:31.000000Z",
"updated_at": "2024-11-04T17:06:31.000000Z",
"tag": "",
"deleted_at": null,
"base_currency": "GHS",
"fx_currency": "GHS",
"fx_rate": 1,
"fx_amount": 130,
"enc_id": "ENC_ID",
"taxes": [],
"total_taxAmount": null,
"amount_left": 130
}
}
Get a Single Bill Item
Sample axios request to get a single bill item
jsconst response = axios.get("/api/v3/bills/:id");
:idrepresents the id of the bill you want to get
The Response object received is same as the response after Creating a Bill
Update a Bill
To update a bill, make a POST request to the /api/v3/bills/:id endpoint.
:idrepresents the id of the bill you want to edit
Check out Creating a Bill to see how to make the request and the shape of the RESPONSE object
Adding Payments to a Bill
You can add payments to a bill in four ways.
- Record Manual Payment
- Pay via Built Wallet
- Pay with Built Overdraft
Add Manual Payment
To manually add payment to a bill, make a POST request to the /api/paybill endpoint. Sample request using axios:
jsconst response = await axios.post(
"/api/paybill",
{
amount: 500.0, // The amount you want to pay
date: "2024-11-13", // The date for adding payment to bill
bill_id: "BILL-7890", // The id of the bill
payment_account: "PAY-456", // The payment account associated with the bill
description: "Payment for electricity bill", // The description of the payment
fx_rate: 1.1, // The foreign exchange rate
fx_amount: 550.0, // The foreign exchange amount
base_currency: "GHS", // The currency of the business
fx_currency: "USD", // The foreign exchange currency
},
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
},
);
Pay via Built Wallet
To add payment to a bill via Built wallet, make a POST request to the /bills/pay endpoint. Sample request using axios:
jsconst response = await axios.post(
"/api/vendor/v2/instantpayment",
{
ticket: "xxxxxxxxxxxxxx", // token gotten after verifying your pin,
payer_account_bank: "Test Bank Account",
payer_account_number: "123456789",
account_bank: "Supplier Bank Account",
account_number: "12345677890" // supplier bank account number,
description: "Instant bill payment",
amount: 1,
method: "wallet",
bill_id: "105918",
payment_accountID: "1201243",
charge: 0,
rate: 1
},
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
},
);
Pay with Built Overdraft
To add payment to a bill via Built overdraft, make a POST request to the /api/overdraft/request endpoint. Sample request using axios:
jsconst response = await axios.post(
"/api/overdraft/request",
{
bill_id: "BILL-2345", // The ID of the bill
amount: 1200.0, // The amount you want to pay
payment_date: "2024-11-20", // The date for adding payment to bill
repayment_period: "12 months", // The period for payment
repayment_due_date: "2025-11-20", // The date due for the payment
interest: 150.0, // The interest amount to be paid
total_amount: 1350.0, // The total amount to pay (amount + interest)
account_number: "123456789", // The number of the account
bank: "XYZ Bank", // The bank associated with the account number
account_name: "John Doe", // The name associated with the account number
},
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
},
);
Add Withholding
To add withholding to a bill, make a POST request to the /bills/withholding endpoint. Sample request using axios:
jsconst response = await axios.post(
"/api/v3/bills/withholding",
{
amount: 200.0, // The amount to be withheld
date: "2024-11-25", // The date for the withholding
bill_id: "BILL-5678", // The id of the bill
},
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
},
);
Remove Withholding
To remove withholding to a bill, make a POST request to the /remove/withholding endpoint. Sample request using axios:
jsconst response = await axios.post(
"/api/v3/bills/removebill/withholding",
{
amount: 200.0, // The amount to be withheld
date: "2024-11-25", // The date for the withholding
bill_id: "BILL-5678", // The id of the bill
},
{
{
headers: {
accept: "application/json",
authorization: "Bearer <API-KEY>",
"content-type": "application/json",
},
}
}
);
Delete a Bill
To remove an income tax payment, make a DELETE request to the /api/v3/bills/:id
id- This represents the ID of the bill you want to delete