--- title: "Replace an invoice" method: PUT path: "/v3/invoices/{invoiceId}" tags: ["invoices"] --- # Replace an invoice `PUT /v3/invoices/{invoiceId}` Update the number of line items in an invoice. You can also update other invoice details. You can use the PUT operation to add, remove, or replace the number of line items in an invoice. A set of rules apply with the PUT operation. * When you add a new line item, a new line item `id` is generated in the invoice. * When you omit an existing line item `id`, the line item is removed from the invoice. ## Path parameters - `invoiceId` string, required — BILL-generated ID of the invoice. The value begins with `00e`. ## Headers - `sessionId` string, nullable — API session ID generated with `/v3/login` - `devKey` string, nullable — Developer key generated with your BILL developer account ## Request body - InvoiceReplaceRequestDto — Replace an invoice (line item added) - `invoiceNumber` string — User-generated invoice number. This value can be your chosen number scheme. If you do not set this field, `invoiceNumber` is auto-generated. - `invoiceDate` string, 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. - `dueDate` string, 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. - `paymentTermId` string - `customer` object, required — Customer contact information. * Set the customer `id` for associating an existing customer to the invoice. * Set `name` and `email` for creating a new customer with the invoice. In the response, a new BILL-generated customer `id` is available. - `id` string — BILL-generated ID of the customer. The value begins with `0cu`. - `name` string — Customer name - `email` string — Customer email address - `invoiceCurrency` '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' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | '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' | 'SLE' | 'SLL' | 'SOS' | 'SPL' | 'SRD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TVD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWD' — Invoice currency. Three-letter abbreviation in the ISO 4217 format. This value is required for an international customer. International customers pay invoices in this currency. - `invoiceLineItems` InvoiceReplaceLineItem[], required — Invoice line item information - `id` string — BILL-generated ID of the invoice line item. The value begins with `00f`. - `description` string — Invoice line item description - `price` number — Invoice line item unit price. For an invoice in an international currency (not USD), this value is in the local currency. - `quantity` number, required — Invoice line item unit quantity - `classifications` object — General ledger classifications information for the invoice line item - `chartOfAccountId` string — BILL-generated ID of the chart of accounts. The value begins with `0ca`. - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`. - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`. - `jobId` string — BILL-generated ID of the job. The value begins with `job`. - `locationId` string — BILL-generated ID of the location. The value begins with `loc`. - `itemId` string — BILL-generated ID of the item. The value begins with `0ii`. - `taxable` boolean — Set as true if the invoice line item is taxable - `processingOptions` object — Invoice processing options - `sendEmail` boolean — Set as `true` to send an email to the customer - `payToChartOfAccountId` string — BILL-generated ID of the chart of accounts for the invoice payment. The value begins with `0ca`. - `classifications` object — General ledger classifications information for the invoice - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`. - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`. - `jobId` string — BILL-generated ID of the job. The value begins with `job`. - `locationId` string — BILL-generated ID of the location. The value begins with `loc`. - `creditAmount` number — Credit amount applied to the invoice. BILL applies the credit amount from the total of all the credit memos available for the customer. - `salesTaxItemId` string — 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`. - `enableCardPayment` boolean — Set as `true` if the card payment option is enabled for the invoice - `convenienceFee` object — Convenience fee information. The customer is charged the convenience fee when they pay the invoice using a card. To set the convenience fee, `enableCardPayment` must be set as `true`. - `percentage` number — Convenience fee percentage - `invoicePdfId` string — 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. ## Response `200` Replace an invoice response - InvoiceResponseDto — Invoices response. - `id` string — BILL-generated ID of the invoice. The value begins with `00e`. - `archived` boolean — 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`. - `invoiceNumber` string — User-generated invoice number. This value can be your chosen number scheme. If you do not set this field, `invoiceNumber` is auto-generated. - `invoiceDate` string, 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. - `dueDate` string, 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. - `paymentTermId` string - `customerId` string — BILL-generated ID of the customer. The value begins with `0cu`. - `totalAmount` number — Invoice total amount - `dueAmount` number — Invoice due amount. The value is calculated by subtracting any applied credits (`creditAmount`), scheduled payment (`scheduledAmount`), and cleared payment from `totalAmount`. - `scheduledAmount` number — Invoice scheduled amount. The value is set as the customer payment amount that is pending clearance. - `creditAmount` number — 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. - `exchangeRate` number — Invoice exchange rate - `createdBy` string — BILL-generated ID of the user that created the invoice. The value begins with `006`. - `createdTime` string, date-time — Invoice created time - `updatedTime` string, date-time — Invoice updated time - `invoiceLineItems` InvoiceResponseLineItem[] — Invoice line item information - `id` string — BILL-generated ID of the invoice line item. The value begins with `00f`. - `description` string — Invoice line item description - `price` number — Invoice line item unit price. For an invoice in an international currency (not USD), this value is in the local currency. - `quantity` number — Invoice line item unit quantity - `classifications` object — General ledger classifications information for the invoice line item - `chartOfAccountId` string — BILL-generated ID of the chart of accounts. The value begins with `0ca`. - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`. - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`. - `jobId` string — BILL-generated ID of the job. The value begins with `job`. - `locationId` string — BILL-generated ID of the location. The value begins with `loc`. - `itemId` string — BILL-generated ID of the item. The value begins with `0ii`. - `taxable` boolean — Set as true if the invoice line item is taxable - `payToChartOfAccountId` string — BILL-generated ID of the chart of accounts for the invoice payment. The value begins with `0ca`. - `payments` InvoicePayment[] — Invoice payments information - `id` string — BILL-generated ID of the invoice payment. The value begins with `0ip`. This ID is generated when a payment is applied to the listed invoice. - `amount` number — Invoice amount paid - `status` 'PAID' | 'VOID' | 'SCHEDULED' | 'CANCELED' | 'INITIATED' | 'UNDEFINED' — Invoice payment status. - `date` string, date — Invoice payment date. The value is in the `yyyy-MM-dd` format. - `classifications` object — General ledger classifications information for the invoice - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`. - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`. - `jobId` string — BILL-generated ID of the job. The value begins with `job`. - `locationId` string — BILL-generated ID of the location. The value begins with `loc`. - `salesTaxItemId` string — 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. - `salesTaxTotal` number — Invoice sales tax amount. The value is set based on `salesTaxItemId`. - `salesTaxPercentage` number — Invoice sales tax percentage. The value is set based on `salesTaxItemId`. - `enableCardPayment` boolean — Set as `true` if the card payment option is enabled for the invoice - `convenienceFee` object — Convenience fee information - `percentage` number — Convenience fee percentage - `invoicePdfId` string — 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. ## Other responses - `4XX` — List of errors. - `5XX` — List of errors. --- [API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/revisions/0483350c434e/schema)