Top

Bills

List bills
GET /bills
List all bills with pagination.
Get a bill
GET /bills/:bill_id
Get the details of a bill.
Create a bill
POST /bills
Create a bill received from your vendor.
Update a bill
PUT /bills/:bill_id
Update a bill. To delete a line item just remove it from the line_items list.
Delete a bill
DELETE /bills/:bill_id
Delete an existing bill. Bills which have payments applied cannot be deleted.
Void a bill
POST /bills/:bill_id/status/void
Mark a bill status as void.
Mark a bill as open
POST /bills/:bill_id/status/open
Mark a void bill as open.
Update billing address
PUT /bills/:bill_id/address/billing
Updates the billing address for this bill.

List bills

GET  /bills

List all bills with pagination.

Parameters

bill_number string
[100]
Search bills by bill number.
Variants: bill_number_startswith and bill_number_contains
reference_number string
[100]
Search bills by reference number.
Variants: reference_number_startswith and reference_number_contains
date string
[yyyy-MM-dd]
Search bills by bill date.
Variants: date_start, date_end, date_before and date.after
status string Search bills by bill status.
Allowed Values: paid, open, overdue, void and partially_paid
description string
[100]
Search bills by description.
Variants: description_startswith and description_contains
vendor_name string
[100]
Search bills by vendor name.
Variants: vendor_name_startswith and vendor_name_contains
total double Search bills by bill total.
Variants: total_less_than, total_less_equals, total_greater_than and total_greater_equals
vendor_id string Search bills by vendor id.
item_id string Search bills by bill item id.
filter_by string Filter bills by any status.
Allowed Values: Status.All, Status.PartiallyPaid, Status.Paid, Status.Overdue, Status.Void and Status.Open
search_text string
[100]
Search bills by bill number or reference number or vendor name.
sort_column string Sort bills.
Allowed Values: vendor_name, bill_number, date, due_date, total, balance and created_time

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "bills": [
    {
      "bill_id": "460000000053199",
      "vendor_id": "460000000026049",
      "vendor_name": "Bowman and Co",
      "status": "overdue",
      "bill_number": "1000",
      "reference_number": "",
      "date": "2013-10-07",
      "due_date": "2013-10-07",
      "due_days": "",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "total": 450.00,
      "balance": 300.00,
      "created_time": "2013-10-07T18:03:42+0530"
    },
    {
      "bill_id": "460000000042035",
      "vendor_id": "460000000038029",
      "vendor_name": "Will Cooper",
      "status": "paid",
      "bill_number": "00454",
      "reference_number": "4321133",
      "date": "2013-09-11",
      "due_date": "2013-09-26",
      "due_days": "",
      "currency_id": "460000000000109",
      "currency_code": "EUR",
      "total": 31.25,
      "balance": 0.00,
      "created_time": "2013-09-11T16:47:38+0530"
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Bills",
    "applied_filter": "Status.All",
    "sort_column": "created_time",
    "sort_order": "D"
  }
}

Get a bill

GET  /bills/:bill_id

Get the details of a bill.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "bill": {
    "bill_id": "460000000042035",
    "vendor_id": "460000000038029",
    "vendor_name": "Will Cooper",
    "unused_credits_payable_amount": 0.00,
    "status": "paid",
    "bill_number": "00454",
    "date": "2013-09-11",
    "due_date": "2013-09-26",
    "reference_number": "4321133",
    "due_by_days": 20,
    "due_in_days": "",
    "currency_id": "460000000000109",
    "currency_code": "EUR",
    "currency_symbol": "€",
    "price_precision": 2,
    "exchange_rate": 1.23,
    "line_items": [
      {
        "line_item_id": "460000000042043",
        "account_id": "460000000000403",
        "account_name": "Advertising And Marketing",
        "description": "",
        "bcy_rate": 12.30,
        "rate": 10.00,
        "quantity": 1.00,
        "tax_id": "460000000027005",
        "tax_name": "VAT",
        "tax_type": "tax",
        "tax_percentage": 12.5,
        "item_total": 10.00,
        "item_order": 1
      },
      {
        "line_item_id": "460000000042045",
        "account_id": "460000000000424",
        "account_name": "Automobile Expense",
        "description": "",
        "bcy_rate": 24.60,
        "rate": 20.00,
        "quantity": 1.00,
        "tax_id": "",
        "tax_name": "",
        "tax_type": "tax",
        "tax_percentage": 0,
        "item_total": 20.00,
        "item_order": 2
      }
    ],
    "sub_total": 30.00,
    "tax_total": 1.25,
    "total": 31.25,
    "taxes": [
      {
        "tax_name": "VAT (12.5%)",
        "tax_amount": 1.25
      }
    ],
    "payment_made": 31.25,
    "balance": 0.00,
    "billing_address": {
      "address": "4900 Hopyard Road #310\n",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "United States",
      "fax": ""
    },
    "payments": [
      {
        "payment_id": "460000000042059",
        "bill_id": "460000000042035",
        "bill_payment_id": "460000000042061",
        "payment_mode": "Cash",
        "description": "",
        "date": "2013-09-11",
        "reference_number": "43218995",
        "exchange_rate": 1.23,
        "amount": 31.25,
        "paid_through_account_id": "460000000000358",
        "paid_through_account_name": "Undeposited Funds",
        "is_single_bill_payment": true
      }
    ],
    "created_time": "2013-09-11T16:47:38+0530",
    "last_modified_time": "2013-09-11T16:48:14+0530",
    "reference_id": "",
    "notes": "Thanks for your business.",
    "terms": "Terms and conditions apply.",
    "attachment_name": ""
  }
}

Create a bill

POST  /bills

Create a bill received from your vendor.

multipart/form-data

attachment file File to attach.
Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf

Request attributes

vendor_id* string ID of the vendor the bill has to be created.
bill_number* string
[50]
The bill number.
date string
[yyyy-MM-dd]
The date the bill was created.
due_date string
[yyyy-MM-dd]
Date bill is due.
exchange_rate double Exchange rate of the currency.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the bill. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
line_items array Line items of a bill.
account_id* string ID of the account associated with the line item.
description string
[2000]
Description of the line item.
rate double Rate of the line item.
quantity double Quantity of the line item.
tax_id
(Not applicable for the US Edition)
string ID of the tax or tax group applied to the line item.
product_type
(UK Edition only)
string Type of the bill. This denotes whether the bill line item is to be treated as a goods or service purchase. This only need to be specified in case purchase order is not enabled.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase and reverse charge VAT needs to be reported.

Sample Request

{
  "vendor_id": "460000000038029",
  "bill_number": "00454",
  "reference_number": "4321133",
  "date": "2013-09-11",
  "due_date": "2013-09-26",
  "exchange_rate": 1.23,
  "line_items": [
    {
      "account_id": "460000000000403",
      "description": "",
      "rate": 10.00,
      "quantity": 1.00,
      "tax_id": "460000000027005",
      "item_order": 1
    },
    {
      "account_id": "460000000000424",
      "description": "",
      "rate": 20.00,
      "quantity": 1.00,
      "tax_id": "",
      "item_order": 2
    }
  ],
  "notes": "Thanks for your business.",
  "terms": "Terms and conditions apply."
}

Sample Response


Status: 201 Created
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The bill has been created.",
  "bill": {
    "bill_id": "460000000042035",
    "vendor_id": "460000000038029",
    "vendor_name": "Will Cooper",
    "unused_credits_payable_amount": 0.00,
    "status": "paid",
    "bill_number": "00454",
    "date": "2013-09-11",
    "due_date": "2013-09-26",
    "reference_number": "4321133",
    "due_by_days": 20,
    "due_in_days": "",
    "currency_id": "460000000000109",
    "currency_code": "EUR",
    "currency_symbol": "€",
    "price_precision": 2,
    "exchange_rate": 1.23,
    "line_items": [
      {
        "line_item_id": "460000000042043",
        "account_id": "460000000000403",
        "account_name": "Advertising And Marketing",
        "description": "",
        "bcy_rate": 12.30,
        "rate": 10.00,
        "quantity": 1.00,
        "tax_id": "460000000027005",
        "tax_name": "VAT",
        "tax_type": "tax",
        "tax_percentage": 12.5,
        "item_total": 10.00,
        "item_order": 1
      },
      {
        "line_item_id": "460000000042045",
        "account_id": "460000000000424",
        "account_name": "Automobile Expense",
        "description": "",
        "bcy_rate": 24.60,
        "rate": 20.00,
        "quantity": 1.00,
        "tax_id": "",
        "tax_name": "",
        "tax_type": "tax",
        "tax_percentage": 0,
        "item_total": 20.00,
        "item_order": 2
      }
    ],
    "sub_total": 30.00,
    "tax_total": 1.25,
    "total": 31.25,
    "taxes": [
      {
        "tax_name": "VAT (12.5%)",
        "tax_amount": 1.25
      }
    ],
    "payment_made": 31.25,
    "balance": 0.00,
    "billing_address": {
      "address": "4900 Hopyard Road #310\n",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "United States",
      "fax": ""
    },
    "payments": [
      {
        "payment_id": "460000000042059",
        "bill_id": "460000000042035",
        "bill_payment_id": "460000000042061",
        "payment_mode": "Cash",
        "description": "",
        "date": "2013-09-11",
        "reference_number": "43218995",
        "exchange_rate": 1.23,
        "amount": 31.25,
        "paid_through_account_id": "460000000000358",
        "paid_through_account_name": "Undeposited Funds",
        "is_single_bill_payment": true
      }
    ],
    "created_time": "2013-09-11T16:47:38+0530",
    "last_modified_time": "2013-09-11T16:48:14+0530",
    "reference_id": "",
    "notes": "Thanks for your business.",
    "terms": "Terms and conditions apply.",
    "attachment_name": ""
  }
}

Update a bill

PUT  /bills/:bill_id

Update a bill. To delete a line item just remove it from the line_items list.

multipart/form-data

attachment file File to replace the existing attachment.
Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf

Request attributes

vendor_id* string ID of the vendor the bill has to be created.
bill_number* string
[50]
The bill number.
date string
[yyyy-MM-dd]
The date the bill was created.
due_date string
[yyyy-MM-dd]
Date bill is due.
exchange_rate double Exchange rate of the currency.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the bill. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
line_items array Line items of a bill.
line_item_id string ID of a line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
account_id* string ID of the account associated with the line item.
description string
[2000]
Description of the line item.
rate double Rate of the line item.
quantity double Quantity of the line item.
tax_id
(Not applicable for the US Edition)
string ID of the tax or tax group applied to the line item.
product_type
(UK Edition only)
string Type of the bill. This denotes whether the bill line item is to be treated as a goods or service purchase. This only need to be specified in case purchase order is not enabled.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase and reverse charge VAT needs to be reported.

Sample Request

{
  "vendor_id": "460000000038029",
  "bill_number": "00454",
  "reference_number": "4321133",
  "date": "2013-09-11",
  "due_date": "2013-09-26",
  "exchange_rate": 1.23,
  "line_items": [
    {
      "line_item_id": "460000000042043",
      "account_id": "460000000000403",
      "description": "",
      "rate": 10.00,
      "quantity": 1.00,
      "tax_id": "460000000027005",
      "item_order": 1
    },
    {
      "line_item_id": "460000000042045",
      "account_id": "460000000000424",
      "description": "",
      "rate": 20.00,
      "quantity": 1.00,
      "tax_id": "",
      "item_order": 2
    }
  ],
  "notes": "Thanks for your business.",
  "terms": "Terms and conditions apply."
}

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Bill information has been updated.",
  "bill": {
    "bill_id": "460000000042035",
    "vendor_id": "460000000038029",
    "vendor_name": "Will Cooper",
    "unused_credits_payable_amount": 0.00,
    "status": "paid",
    "bill_number": "00454",
    "date": "2013-09-11",
    "due_date": "2013-09-26",
    "reference_number": "4321133",
    "due_by_days": 20,
    "due_in_days": "",
    "currency_id": "460000000000109",
    "currency_code": "EUR",
    "currency_symbol": "€",
    "price_precision": 2,
    "exchange_rate": 1.23,
    "line_items": [
      {
        "line_item_id": "460000000042043",
        "account_id": "460000000000403",
        "account_name": "Advertising And Marketing",
        "description": "",
        "bcy_rate": 12.30,
        "rate": 10.00,
        "quantity": 1.00,
        "tax_id": "460000000027005",
        "tax_name": "VAT",
        "tax_type": "tax",
        "tax_percentage": 12.5,
        "item_total": 10.00,
        "item_order": 1
      },
      {
        "line_item_id": "460000000042045",
        "account_id": "460000000000424",
        "account_name": "Automobile Expense",
        "description": "",
        "bcy_rate": 24.60,
        "rate": 20.00,
        "quantity": 1.00,
        "tax_id": "",
        "tax_name": "",
        "tax_type": "tax",
        "tax_percentage": 0,
        "item_total": 20.00,
        "item_order": 2
      }
    ],
    "sub_total": 30.00,
    "tax_total": 1.25,
    "total": 31.25,
    "taxes": [
      {
        "tax_name": "VAT (12.5%)",
        "tax_amount": 1.25
      }
    ],
    "payment_made": 31.25,
    "balance": 0.00,
    "billing_address": {
      "address": "4900 Hopyard Road #310\n",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "United States",
      "fax": ""
    },
    "payments": [
      {
        "payment_id": "460000000042059",
        "bill_id": "460000000042035",
        "bill_payment_id": "460000000042061",
        "payment_mode": "Cash",
        "description": "",
        "date": "2013-09-11",
        "reference_number": "43218995",
        "exchange_rate": 1.23,
        "amount": 31.25,
        "paid_through_account_id": "460000000000358",
        "paid_through_account_name": "Undeposited Funds",
        "is_single_bill_payment": true
      }
    ],
    "created_time": "2013-09-11T16:47:38+0530",
    "last_modified_time": "2013-09-11T16:48:14+0530",
    "reference_id": "",
    "notes": "Thanks for your business.",
    "terms": "Terms and conditions apply.",
    "attachment_name": ""
  }
}

Delete a bill

DELETE  /bills/:bill_id

Delete an existing bill. Bills which have payments applied cannot be deleted.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The bill has been deleted."
}

Void a bill

POST  /bills/:bill_id/status/void

Mark a bill status as void.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The bill has been marked as void"
}

Mark a bill as open

POST  /bills/:bill_id/status/open

Mark a void bill as open.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The status of the bill has been changed from void to open"
}

Update billing address

PUT  /bills/:bill_id/address/billing

Updates the billing address for this bill.

Request attributes

is_update_customer boolean You can set this address as default shipping address for your customer from now on by specifying param as true.

Sample Request

{
      "address": "4900 Hopyard Road #310",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "United States",
      "fax": "+1-925-924-9600",
      "is_update_customer": false
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Billing address updated"
    }