Skip to main content
PUT
Update Bill record
Validates all required fields and business rules. Side effects
  • If an approval workflow matches this request, DualEntry can set record_status back to draft.
Additional validations
  • Fails with 422 when the AP account is missing, inactive, of a type that is not allowed, in another company, or not the intercompany AP account on an intercompany record.
  • Fails with 422 if you set an inactive, archived, or draft customer or vendor, or an inactive company.
  • Fails with 422 if a line account is not available to the record’s company.
  • Fails with 422 if you set the customer or vendor that stands for the record’s own company as a party.
  • A reference that the record or its linked source record already holds passes these checks.

Authorizations

X-API-KEY
string
header
required

Headers

Idempotency-Key
string

Optional. A unique value (a UUID works well) identifying this operation. If the request is repeated with the same key, the original response is replayed instead of the operation running again, so a retry cannot create a duplicate record. Results are replayable for 48 hours. Reusing a key with a different request body returns 422.

Maximum string length: 255

Path Parameters

record_number
integer
required

The number attribute of the record.

Body

application/json
date
string<date>
required
company_id
integer
required
vendor_id
integer
required

If this vendor is intercompany, DualEntry also writes a transaction in the elimination company.

withholding_tax_payable_account_id
integer | null

ID of the liability account for the withheld amounts. When you send null, or omit the field on create, DualEntry uses the default_withholding_tax_payable_account_id of the vendor. A record with withholding tax needs one of the two. On an update, an omitted value keeps the stored account.

ship_from_address
AddressSchemaIn · object | null
ship_to_address
AddressSchemaIn · object | null
supply_date
string<date> | null

Tax point date for VAT and GST.

When the saved record uses a VAT or GST tax regime and you omit this field, DualEntry sets it to transaction_date, or to date when there is no transaction_date.

Recurring templates store the value you send. Each generated record that uses VAT or GST and has no supply date gets that default on save.

On PATCH, an omitted field keeps the stored value. Send supply_date again when you change date or transaction_date.

place_of_supply
string | null
Maximum string length: 2
tax_registration_numbers
TaxRegistrationNumbersSnapshot · object | null
tax_metadata
object | null
custom_fields
Custom Fields · object[] | null
transaction_date
string<date> | null
auto_calculate_tax
enum<string> | null

Configures how to handle automatic tax calculations.

If auto_calculate_tax is unset, the tax you send on each line is stored. Set it to required to have DualEntry calculate the tax, replacing the tax on every line before it saves the record.

The calculation covers native US sales tax using DualEntry's tax engine. It also covers Avalara US sales tax, VAT, and GST.

  • For native VAT and GST, leave this field unset and send the rate and the tax on each line. Set it to required when a tax provider returns the tax.
  • The request fails with 422 when the result is DualEntry's own VAT or GST, when the calculation cannot finish, or when a required address is still missing.
  • When the record has a customer, DualEntry reads shipping_address, then billing_address, then the address saved on the customer.
  • If you send neither address, DualEntry copies the customer's saved address to billing_address and shipping_address.
  • When the record has a vendor, DualEntry reads ship_from_address and ship_to_address, then the addresses saved on the vendor and the company.
  • DualEntry stores only the ship addresses you sent.
Available options:
required
currency_iso_4217_code
enum<string> | null
Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLF,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XAG,
XAU,
XCD,
XDR,
XOF,
XPD,
XPF,
XPT,
YER,
ZAR,
ZMW,
ZWL
exchange_rate
memo
string | null
Maximum string length: 512
items
PublicBillItemIn · object[] | null
expenses
PublicBillExpenseIn · object[] | null
due_date
string<date> | null
term_id
integer | null
reference_number
string
default:""
purchase_order_number
integer | null
ap_account_id
integer | null

ID of the AP account. The default is the intercompany AP account on an intercompany bill. On other bills, it is the vendor default, then the company default, then the system AP account. The account must be active, belong to the bill company or to no company, and be accounts payable, credit card, or other current liability.

An update without this field keeps the stored account, unless it changes the vendor or the company. On v3, or with the public API breaking changes, a PUT without this field uses the default. Send null to use the default.

attachments
AttachmentSchemaOut · object[]
record_status
enum<string>
default:posted
Available options:
draft,
posted,
archived

Response

OK

supply_date
string<date> | null
required
tax
RecordTaxContextOut · object | null
required

Base for record-level tax context; regime discriminates data.

Mirrors TaxResultV2Out (core.taxes.api.taxes)

transaction_ids
integer[]
required
term_id
integer | null
required
term_name
string
required
internal_id
integer
required
number
integer
required
date
string<date>
required

Posting date (GL date) - the date when the transaction is recorded in the general ledger

transaction_date
string<date>
required

Transaction date (inception date) - the date when the transaction actually occurred

due_date
string<date>
required
company_id
integer
required
company_name
string
required
company_currency
string
required
vendor_id
integer
required
vendor_name
string
required
ap_account_id
integer
required
currency_iso_4217_code
enum<string>
required
Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLF,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XAG,
XAU,
XCD,
XDR,
XOF,
XPD,
XPF,
XPT,
YER,
ZAR,
ZMW,
ZWL
exchange_rate
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,16}0*$
memo
string
required
amount
string
required

Total amount of transaction

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
amount_due
string
required

Amount to be paid

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
paid_total
string
required

Amount that was already paid by Vendor Prepayment Applications or Vendor Payments

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
items
PublicBillItemOut · object[]
required
expenses
PublicBillExpenseOut · object[]
required
record_status
enum<string>
required
Available options:
draft,
posted,
archived
recurring_record_number
integer | null
required
purchase_order_number
integer | null
required
reference_number
string
required
created_at
string<date-time>
required

Date and time the record was created

updated_at
string<date-time>
required

Date and time the record was last updated

custom_fields
CustomFieldValuePairOutputSchema · object[]
withholding_tax_total
string
default:0.00

Sum of the withheld amounts of the lines

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
withholding_tax_payable_account_id
integer | null

ID of the liability account for the withheld amounts of the record.

ship_from_address
AddressSchemaOut · object | null
ship_to_address
AddressSchemaOut · object | null
place_of_supply
string | null
Maximum string length: 2
tax_registration_numbers
TaxRegistrationNumbersSnapshot · object | null
tax_metadata
object | null
attachments
PublicAttachmentSchemaOut · object[]
bank_match_status
string | null
reconciliation_status
string | null
created_by
AuditActorSchemaOut · object | null

Schema for audit actor information.

updated_by
AuditActorSchemaOut · object | null

Schema for audit actor information.

approval_status
string | null
next_approvers
ApproverDictSchema · object[] | null
rejected_by
RejectedBySchema · object | null

Schema for rejector information including rejection reason.

code
string | null