What is the Cosmos DB transactional batch API?

The transactional batch API is the way to execute multiple operations (up to 100) atomically on items that share the same partition key. Unlike stored procedures (which also provide ACID atomicity but require JavaScript and have size limits), the transactional batch runs from the client SDK and does not require any server-side registration.

A batch groups read, write, replace, delete, and patch operations together. The entire batch either commits or fails together — no partial success. If any single operation in the batch fails (e.g., a precondition check fails), the entire batch rolls back and the response contains which operation failed and why.

// C# example: atomic batch for same partition key "order-456"
TransactionalBatch batch = container.CreateTransactionalBatch(
    new PartitionKey("order-456"));

batch.CreateItem(new OrderItem { id = "item-1", orderId = "order-456", sku = "ABC" });
batch.ReplaceItem("order-456", new Order { id = "order-456", status = "processing" });
batch.DeleteItem("temp-hold-456");

TransactionalBatchResponse response = await batch.ExecuteAsync();
if (!response.IsSuccessStatusCode)
{
    // Check response[0].StatusCode, response[1].StatusCode, etc. for failure details
}

The batch API is the preferred way to handle multi-document transactions in modern Cosmos DB applications because it is cleaner than stored procedures, supports all SDK languages (no JavaScript constraint), and has a defined 100-operation limit per batch. It is ideal for patterns like: update an order header + insert multiple line items atomically, or implement optimistic concurrency by checking an item's ETag in a batch precondition before updating it.

The one constraint that matches stored procedures: all items in the batch must share the same partition key value. Cross-partition multi-document atomicity is not supported in Cosmos DB.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.