---
title: "Update Bulk Invoices (Sync)"
method: PUT
path: "/invoices"
tags: ["invoice > bulk"]
---

# Update Bulk Invoices (Sync)

`PUT /invoices`

## Request

- Base URL: `https://api.mercoa.com`
- URL: `https://api.mercoa.com/invoices`
- Auth: HTTP bearer

Update multiple invoices in bulk. This endpoint will process synchronously and return a list of invoices that were updated or failed to update.

## Query parameters

- `emitWebhooks` boolean

## Request body

- InvoiceTypesBulkInvoiceUpdateRequest
  - `invoices` InvoiceTypesInvoiceUpdateRequestWithId[], required
    - `status` 'UNASSIGNED' | 'DRAFT' | 'NEW' | 'APPROVED' | 'SCHEDULED' | 'PENDING' | 'PAID' | 'ARCHIVED' | 'REFUSED' | 'CANCELED' | 'FAILED'
    - `amount` number, double: Total amount of invoice in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.
    - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'COP' | 'COU' | 'CRC' | 'CUC' | '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' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'CNY' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'
    - `invoiceDate` string, date-time: Date the invoice was issued.
    - `deductionDate` string, date-time: Initial date when funds are scheduled to be deducted from payer's account.
    - `settlementDate` string, date-time: Date of funds settlement.
    - `dueDate` string, date-time: Due date of invoice.
    - `invoiceNumber` string
    - `noteToSelf` string: Note to self or memo on invoice.
    - `serviceStartDate` string, date-time
    - `serviceEndDate` string, date-time
    - `netTerms` integer: Net terms in days. Must be a positive number.
    - `payerId` string
    - `paymentSourceId` string
    - `paymentSourceOptions` InvoiceTypesPaymentSourceOptions
      - `type` 'bnpl', required: Discriminator value: bnpl
      - `installmentsStartDate` string, required: The start date for installments in YYYY-MM-DD format
      - `defermentWeeks` integer, required: The number of weeks to defer repayment
      - `acceptedTerms` boolean, required: Whether the user has agreed to the BNPL terms
      - `loanId` string: The ID of the loan to use for the BNPL payment.
      - `downpaymentId` string: The ID of the downpayment to use for the BNPL payment.
    - `vendorId` string
    - `paymentDestinationId` string
    - `paymentDestinationOptions` union
      - object
        - `type` 'check', required: Discriminator value: check
        - `delivery` 'PRINT' | 'MAIL' | 'MAIL_PRIORITY' | 'MAIL_UPS_NEXT_DAY'
        - `printDescription` boolean: If true, prints the invoice description (noteToSelf) on the check note. Defaults to false.
      - object
        - `type` 'bankAccount', required: Discriminator value: bankAccount
        - `delivery` 'ACH_STANDARD' | 'ACH_SAME_DAY' | 'ACH_ACCELERATED'
        - `description` string: ACH Statement Description. By default, this will be 'AP' followed by the first 8 characters of the invoice ID (for a single invoice) or the first 8 characters of the transaction ID (for a batch payment). Must be at least 4 characters and no more than 10 characters, and follow this regex pattern `^[a-zA-Z0-9\-#.$&* ]{4,10}$`
      - object
        - `type` 'utility', required: Discriminator value: utility
        - `accountId` string, required: The ID for the utility account to pay with. Links to accounts listed on payor/payee relationship.
      - object
        - `type` 'custom', required: Discriminator value: custom
        - `dynamicUrls` object: Map of field names to dynamic URL values that will be used for dynamicUrl fields in custom payment method schemas
    - `approvers` InvoiceTypesApprovalSlotAssignment[]: Set approvers for this invoice.
      - `approvalSlotId` string, required
      - `assignedUserId` string, required
    - `metadata` object: Metadata associated with this invoice.
    - `foreignId` string: The ID used to identify this invoice in your system. This ID must be unique within each creatorEntity in your system, e.g. two invoices with the same creatorEntity may not have the same foreign ID.
    - `document` string: Base64-encoded string. Supported file types include PNG, JPG, WEBP, PDF, and all Microsoft Office formats (automatically converted to PDF). Max file size 10MB. If the invoice already has a document, this will add a new document to the invoice.
    - `uploadedImage` string: DEPRECATED. Use document field instead.
    - `creatorUserId` string
    - `failureType` 'SOURCE_PAYMENT_ERROR' | 'DESTINATION_PAYMENT_ERROR' | 'REJECTED_HIGH_RISK' | 'INSUFFICIENT_FUNDS' | 'PROCESSING_ERROR'
    - `fees` InvoiceTypesInvoiceFeesRequest
      - `sourcePlatformMarkupFee` number, double, required: Fee charged to the payer (C2).
      - `destinationPlatformMarkupFee` number, double, required: Fee charged to the payee (C3).
    - `batchPayment` boolean: If true, this invoice will be paid as a batch payment. Batches are automatically determined by Mercoa based on the payment source, destination, and scheduled payment date.
    - `paymentSchedule` union
      - object
        - `type` 'oneTime', required: Discriminator value: oneTime
        - `repeatEvery` integer: How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week.
        - `ends` union
          - integer
          - string, date-time
      - object
        - `type` 'daily', required: Discriminator value: daily
        - `repeatEvery` integer: How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week.
        - `ends` union
          - integer
          - string, date-time
      - object
        - `type` 'weekly', required: Discriminator value: weekly
        - `repeatEvery` integer: How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week.
        - `ends` union
          - integer
          - string, date-time
        - `repeatOn` InvoiceTypesDayOfWeek[], required
      - object
        - `type` 'monthly', required: Discriminator value: monthly
        - `repeatEvery` integer: How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week.
        - `ends` union
          - integer
          - string, date-time
        - `dayOffset` integer: deprecated. will be removed in the future and will always be 0.
        - `repeatOnDay` integer, required: Day of the month to repeat on. Positive values (1-31): Represent the day of the month counting from the start (e.g., 10 is the 10th day of the month). Negative values (-1 to -31): Represent the day of the month counting backward from the end (e.g., -1 is the last day of the month, -2 is the second-to-last day).
      - object
        - `type` 'yearly', required: Discriminator value: yearly
        - `repeatEvery` integer: How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week.
        - `ends` union
          - integer
          - string, date-time
        - `repeatOnDay` integer, required: Day of the month to repeat on. Positive values (1-31): Represent the day of the month counting from the start (e.g., 10 is the 10th day of the month). Negative values (-1 to -31): Represent the day of the month counting backward from the end (e.g., -1 is the last day of the month, -2 is the second-to-last day).
        - `repeatOnMonth` integer, required: Month to repeat on (1-12).
    - `vendorCreditIds` VendorCreditTypesVendorCreditId[]: The IDs of the vendor credits to be applied to this invoice. Passing this field will un-apply any previously applied vendor credits.
    - `taxAmount` number, double: Tax amount for this invoice.
    - `shippingAmount` number, double: Shipping amount for this invoice.
    - `ocrJobId` string
    - `paymentDestinationConfirmed` boolean: Set to true if the payment destination has been confirmed by the vendor or if the payment destination should default to the selected payment destination on the vendor portal.
    - `lineItems` InvoiceTypesInvoiceLineItemUpdateRequest[]
      - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'COP' | 'COU' | 'CRC' | 'CUC' | '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' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'CNY' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'
      - `name` string
      - `quantity` number, double
      - `unitPrice` number, double: Unit price of the line item in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.
      - `category` string: Category of the line item.
      - `serviceStartDate` string, date-time
      - `serviceEndDate` string, date-time
      - `metadata` object
      - `glAccountId` string: ID of general ledger account associated with this line item.
      - `id` string: If provided, will overwrite line item on the invoice with this ID. If not provided, will create a new line item.
      - `amount` number, double: Total amount of line item in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.
      - `description` string
    - `creatorEntityId` string
    - `invoiceId` string, required

## Response `200`

Response with status 200

- InvoiceTypesBulkInvoiceUpdateResponse
  - `data` InvoiceTypesBulkInvoiceUpdateFromObjectResponse[], required
    - `id` string
    - `foreignId` string: If provided, this is the foreign ID of the invoice that was updated.
    - `error` string: The error message if the invoice was not updated

## Other responses

- `400`: Error response with status 400
- `401`: Error response with status 401
- `403`: Error response with status 403
- `404`: Error response with status 404
- `409`: Error response with status 409
- `500`: Error response with status 500
- `501`: Error response with status 501

---

[API](https://skmtc.dev/mercoa/apis/mercoa-2.md) - [All operations](https://skmtc.dev/mercoa/apis/mercoa-2/llms.txt) - [OpenAPI document](https://skmtc.dev/mercoa/apis/mercoa-2/revisions/00a8e403ae18?raw)