Bulk writes

Last updated: September 28, 2026

Overview

Merge's bulk writes feature enables you to create multiple objects in a single API call, rather than making separate requests for each individual object. This capability is designed for high-volume write operations, allowing you to efficiently scale your integration workflows while minimizing API overhead and staying within third-party rate limits.

Endpoints

POST /<common_model>/bulk

  • Immediately returns a batch_id

  • The task executes asynchronously in the background.

  • Customers can use the batch_id to poll for status and per-object results.

GET /<common_model>/bulk/<batch_id>

  • Returns metadata (status) about each object in the batch.

Integration support

The bulk write endpoint currently supports the following integrations + common models.

Integration

Common Models

NetSuite

Invoices

Item Fulfillments

Sales Orders

QuickBooks Online

Expenses

Invoices

Sage Intacct

Expenses

Xero

Expenses

Payloads

POST /<common_model>/bulk

Request body

A sample of a request body to /invoices/bulk is shown below. The request body must adhere to the following requirements:

  • Max payload size of 5 MB or max of 100 objects

  • Each object must contain a unique item_id

    • This is passed to the third-party API to uniquely identify the item, and maps to the item’s ID in the third party.

  • Each object should be identical in structure to the payload used in the single-object create (POST) endpoint for common models

 {
	"batch_items": [
		{
			"item_id": "1",
			"payload": {
			  "type": "ACCOUNTS_RECEIVABLE",
			  "contact": "022a2bef-57e5-4def-8ed2-7c41bd9a5ed8",
			  "number": "AIQ12546",
			  "issue_date": "2020-03-31T00:00:00Z",
			  "due_date": "2020-04-15T00:00:00Z",
			  "paid_on_date": "2020-04-01T00:00:00Z",
			  "memo": "Weekly Payment",
			  "company": "595c8f97-2ac4-45b7-b000-41bdf43240b5",
			  "employee": "7442f0d5-722d-45bd-b807-6e38489d37fe",
			  "currency": "USD",
			  "exchange_rate": "2.9",
			  "payment_term": "89d329de-825f-4ac6-8369-3c58b4e68bee",
			  "total_discount": 0,
			  "sub_total": 100,
			  "status": "DRAFT",
			  "total_tax_amount": 5,
			  "total_amount": 105,
			  "balance": 105,
			  "tracking_categories": [
			    "7dc5ca17-d311-44cd-9ce0-333080367a18"
			  ],
			  "accounting_period": "7dc5ca17-d311-44cd-9ce0-333080367a18",
			  "line_items": [
			    {
			      "description": "Pickleball lessons",
			      "unit_price": 50,
			      "quantity": 1,
			      "total_amount": 50,
			      "currency": "USD",
			      "exchange_rate": "2.9",
			      "employee": "7442f0d5-722d-45bd-b807-6e38489d37fe",
			      "tax_rate": "a12e7c20-1922-9df7-s75n-edfeewnn7384",
			      "item": "5b3c1341-a20f-4e51-b72c-f3830a16c97b",
			      "account": "cd0f32d4-a493-11ec-b909-0242ac120002",
			      "project": "22e65a5d-2df5-4e6e-884a-e538d0339000",
			      "contact": "908934-49j9-093f-0989-908923908",
			      "tracking_categories": [
			        "b38c59b0-a9d7-4740-b1ee-5436c6751e3d"
			      ],
			      "company": "595c8f97-2ac4-45b7-b000-41bdf43240b5"
			        }
			  ],
			  "inclusive_of_tax": true
			}
		}
	]
}

Response body

{
    "batch_id": "d0a3ca3e-2d7a-44cd-a94b-bda805f23b5c"
}

GET /<common_model>/bulk/<batch_id>

{
  "batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PARTIAL_SUCCESS",
  "total_count": 2,
  "objects": [
    {
      "item_id": "1",
      "status": "SUCCESS",
      "response": {
        "merge_common_model_id": "9871b4a9-f5d2-4f3b-a66b-dfedbed42c46"
      }
    },
    {
      "item_id": "2",
      "status": "FAILURE",
      "response": {
        "error_message": "You cannot update this invoice at this time"
      }
    }
  ]
}

Possible overall statuses

  • ENQUEUED - The request has been received and a task has been enqueued for processing

  • IN_PROGRESS - The enqueued task is being processed

  • PARTIAL_SUCCESS - The task has been processed, but not all objects were written successfully

  • SUCCESS - The task has been processed, and all objects were written successfully

  • FAILED - The task has been processed, but ran into an error while processing

  • RATE_LIMITED - The request was received but ran into rate limits while processing. The rate limited objects are being retried.

Possible per-object statuses

  • PENDING - This object has not been processed yet

  • SUCCESS - This object was successfully POSTed

  • FAILURE - This object was not successfully POSTed

Questions

If you have questions, or want to request coverage for additional integrations or common models, reach out to your CSM or [email protected].