BIbill
invoices

Update an invoice

Changed on

Update details about an invoice line item. You can also update other invoice details.

You can use the PATCH operation to modify line item details, such as amount, quantity, and description. The invoice line item id does not change with a PATCH operation.

patch/v3/invoices/{invoiceId}

Request

  • Base URL
    https://gateway.stage.bill.com/connect
  • URL
    https://gateway.stage.bill.com/connect/v3/invoices/{invoiceId}
  • Auth
    none declared

Path parameters

invoiceIdstring required

BILL-generated ID of the invoice. The value begins with 00e.

Example:{{invoice_id}}

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

invoiceNumberstring

User-generated invoice number. This value can be your chosen number scheme.

If you do not set this field, invoiceNumber is auto-generated.

invoiceDatestring date

Invoice creation date. This value is in the yyyy-MM-dd format.

If you do not set this field, invoiceDate is set as the date when the invoice is created.

dueDatestring date

Invoice due date. The value is in the yyyy-MM-dd format.

If you do not set this field, dueDate is set as the date when the invoice is created.

paymentTermIdstring
payToChartOfAccountIdstring

BILL-generated ID of the chart of accounts for the invoice payment. The value begins with 0ca.

creditAmountnumber

Credit amount applied to the invoice.

BILL applies the credit amount from the total of all the credit memos available for the customer.

enableCardPaymentboolean

Set as true if the card payment option is enabled for the invoice

salesTaxItemIdstring

BILL-generated ID of the SALES_TAX item. The value begins with 0ii. The tax rate is applied to all the invoice line items set as taxable.

You can set up a SALES_TAX percentage item with POST /v3/classifications/items.

invoicePdfIdstring

BILL-generated ID of the invoice PDF. The value begins with att.

The invoice PDF is sent as an email attachment when you send an invoice to a customer. The invoice PDF also appears when the customer clicks the invoice payment link to complete the invoice payment.

Note: You can get the list of invoice attachments with GET /v3/attachments/invoices/{invoiceId}. All the attachments in the list (including the invoice PDF) are sent as email attachments when you send the invoice to the customer.

Example request

{
  "invoiceLineItems": [
    {
      "id": "{{invoice_line_item_id01}}",
      "quantity": 2,
      "description": "Classic extreme drum sticks (amount updated)",
      "price": 19.99
    }
  ]
}

Response

Update an invoice response

idstring

BILL-generated ID of the invoice. The value begins with 00e.

archivedboolean

Set as true if the invoice is archived

recordStatus'ACTIVE' | 'INACTIVE' | 'DRAFT' | 'UNDEFINED'

Invoice record status.

When recordStatus is ACTIVE, archived is set as false. For any other recordStatus value, archived is set as true.

invoiceNumberstring

User-generated invoice number. This value can be your chosen number scheme.

If you do not set this field, invoiceNumber is auto-generated.

invoiceDatestring date

Invoice creation date. This value is in the yyyy-MM-dd format.

If you do not set this field, invoiceDate is set as the date when the invoice is created.

dueDatestring date

Invoice due date. The value is in the yyyy-MM-dd format.

If you do not set this field, dueDate is set as the date when the invoice is created.

paymentTermIdstring
customerIdstring

BILL-generated ID of the customer. The value begins with 0cu.

customerNamestring

Name of the customer the invoice is issued to.

totalAmountnumber

Invoice total amount

dueAmountnumber

Invoice due amount. The value is calculated by subtracting any applied credits (creditAmount), scheduled payment (scheduledAmount), and cleared payment from totalAmount.

scheduledAmountnumber

Invoice scheduled amount. The value is set as the customer payment amount that is pending clearance.

creditAmountnumber

Credit amount applied to the invoice.

When a credit amount is applied to an invoice, the invoice status is set as PARTIAL_PAYMENT or PAID_IN_FULL depending on the invoice totalAmount.

status'PAID_IN_FULL' | 'OPEN' | 'PARTIAL_PAYMENT' | 'SCHEDULED' | 'UNDEFINED'

Invoice status.

exchangeRatenumber

Invoice exchange rate

createdBystring

BILL-generated ID of the user that created the invoice. The value begins with 006.

createdTimestring date-time

Invoice created time

updatedTimestring date-time

Invoice updated time

payToChartOfAccountIdstring

BILL-generated ID of the chart of accounts for the invoice payment. The value begins with 0ca.

salesTaxItemIdstring

BILL-generated ID of the SALES_TAX item. The value begins with 0ii. The tax rate is applied to all the invoice line items set as taxable.

salesTaxTotalnumber

Invoice sales tax amount. The value is set based on salesTaxItemId.

salesTaxPercentagenumber

Invoice sales tax percentage. The value is set based on salesTaxItemId.

enableCardPaymentboolean

Set as true if the card payment option is enabled for the invoice

invoicePdfIdstring

BILL-generated ID of the invoice PDF. The value begins with att.

The invoice PDF is sent as an email attachment when you send an invoice to a customer. The invoice PDF also appears when the customer clicks the invoice payment link to complete the invoice payment.

nonFinanceableReason'INACTIVE' | 'PAID_BY_CUSTOMER' | 'ALREADY_FINANCED_OR_SCHEDULED_TO_FINANCE' | 'ALREADY_FINANCED' | 'AWAITING_CUSTOMER_ACCEPTANCE' | 'INSUFFICIENT_CREDIT' | 'BELOW_MINIMUM_AMOUNT' | 'UNABLE_TO_FINANCE' | 'DUE_DATE_NOT_ELIGIBLE' | 'NO_LONGER_ELIGIBLE' | 'PAST_DUE_BALANCE_REPAY_CURRENT_AMOUNT_DUE' | 'APPLICATION_NOT_APPROVED' | 'AMOUNT_INCREASED_NOT_APPROVED' | 'AUTO_FINANCING_SCHEDULED' | 'FINANCING_IN_PROGRESS' | 'ELIGIBILITY_UNKNOWN_CONTACT_SUPPORT' | 'BANK_ACCOUNT_WAITING_PERIOD_OR_MFA_NOT_ENABLED' | 'UNDEFINED'

Reason the invoice is not eligible for financing. This field is empty when the invoice is eligible or the reason is not available.

  • INACTIVE: Invoice is inactive.
  • PAID_BY_CUSTOMER: Invoice was paid by the customer.
  • ALREADY_FINANCED_OR_SCHEDULED_TO_FINANCE: Invoice was already financed or is scheduled for automatic financing.
  • ALREADY_FINANCED: Invoice was already financed and can't be financed again.
  • AWAITING_CUSTOMER_ACCEPTANCE: Your customer hasn't accepted the invoice yet. When they do, we'll determine eligibility
  • INSUFFICIENT_CREDIT: You don't have enough available credit.
  • BELOW_MINIMUM_AMOUNT: Invoice doesn't meet the required minimum amount.
  • UNABLE_TO_FINANCE: Unable to finance this invoice at this time.
  • DUE_DATE_NOT_ELIGIBLE: Due date is later than Invoice Financing allows.
  • NO_LONGER_ELIGIBLE: Invoice is no longer eligible for financing.
  • PAST_DUE_BALANCE_REPAY_CURRENT_AMOUNT_DUE: You have a past due balance. To finance more invoices, repay the current amount due.
  • APPLICATION_NOT_APPROVED: We're unable to approve your Invoice Financing application at this time.
  • AMOUNT_INCREASED_NOT_APPROVED: Invoice amount was increased after it was sent and your customer hasn't approved it. You can revert the invoice to the original amount or wait for the customer to approve the new amount.
  • AUTO_FINANCING_SCHEDULED: Invoice is scheduled for automatic financing.
  • FINANCING_IN_PROGRESS: Invoice is already in the process of being financed.
  • ELIGIBILITY_UNKNOWN_CONTACT_SUPPORT: Unable to identify the financing eligibility of this invoice. Contact support directly for more information.
  • BANK_ACCOUNT_WAITING_PERIOD_OR_MFA_NOT_ENABLED: Bank account is either new and has a 7 day waiting period or you need to setup MFA to ensure your account is protected.
  • UNDEFINED: Unable to identify the financing eligibility of this invoice. Contact support directly for more information.

Changes

  • 54edddceb0a5Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status