DynamoDB Transactions: Limits, Costs and Working Examples

DynamoDB transactions atomically read or write up to 100 unique items, with at most 4 MB of aggregate item data, across tables in one AWS account and Region. TransactWriteItems commits every action or none; TransactGetItems returns an atomic view of the requested items. Transactional operations consume twice the capacity of equivalent ordinary writes or strongly consistent reads, and MRSC global tables do not support them.

What is an ACID transaction?

A transaction groups related changes into one database operation. Consider a transfer between accounts: subtracting from account A and adding to account B must either both happen or neither happen. Two independent writes can leave only the debit committed if the application crashes before the credit. A transaction avoids that partial result.

The four ACID properties describe the guarantee:

• Atomicity: every action commits together, or the transaction makes no changes.
• Consistency: the transaction preserves the rules you encode in its conditions and data model. DynamoDB does not invent business constraints such as sufficient balance.
• Isolation: concurrent operations follow the documented isolation rules. The multi-item transactional APIs provide a stronger grouping than independent requests.
• Durability: a successfully committed transaction persists despite subsequent application failure.

DynamoDB transactions are submitted as a complete request. There is no BEGIN session that stays open while your application waits for user input or computes its next statement.

Why transactions are important

Use transactions when a rule spans items: reserving stock and recording a cart entry, moving value between accounts, creating an entity and its unique-name reservation, or writing a durable idempotency record together with a business change.

A condition check on a separate entitlement item can make a database change depend on that entitlement's state within the transaction. That is an application rule, not a substitute for IAM authorization.

If the entire rule fits in one item, an ordinary conditional write is usually enough. A single UpdateItem can atomically check remaining stock and decrement it without a transaction. Add the transaction when another item must change with it.

Transaction limits and supported actions

The TransactWriteItems API reference is the source for request limits and error shapes. A transaction's four action types are:

• Put: create or replace a complete item, optionally with a condition.
• Update: change attributes through an update expression, optionally with a condition.
• Delete: delete the keyed item, optionally with a condition.
• ConditionCheck: assert a condition on an item that the transaction does not modify.

When a condition concerns the item being updated, put it directly on Update. A separate ConditionCheck for that same item would violate the one-action-per-item rule.

How to do transactions using Node.js and SDK v3

This example uses Cart and Items, each with a string partition key named id. The inventory item 777-000 must already exist with a numeric count. The transaction creates cart entry 777 only if it is absent and reduces inventory only if enough remains.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, TransactWriteCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

export async function reserveItem(requestToken, cartId, itemId, quantity) {
  if (!Number.isInteger(quantity) || quantity <= 0) {
    throw new Error("quantity must be a positive integer")
  }

  return db.send(new TransactWriteCommand({
    ClientRequestToken: requestToken,
    ReturnConsumedCapacity: "TOTAL",
    TransactItems: [
      {
        Put: {
          TableName: "Cart",
          Item: { id: cartId, itemId, count: quantity },
          ConditionExpression: "attribute_not_exists(id)",
          ReturnValuesOnConditionCheckFailure: "ALL_OLD",
        },
      },
      {
        Update: {
          TableName: "Items",
          Key: { id: itemId },
          UpdateExpression: "SET #count = #count - :quantity",
          ConditionExpression: "#count >= :quantity",
          ExpressionAttributeNames: { "#count": "count" },
          ExpressionAttributeValues: { ":quantity": quantity },
          ReturnValuesOnConditionCheckFailure: "ALL_OLD",
        },
      },
    ],
  }))
}

// Keep this same token and payload for retries of this business request.
await reserveItem("reservation-777-attempt-1", "777", "777-000", 1)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, TransactWriteCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

export async function reserveItem(requestToken, cartId, itemId, quantity) {
  if (!Number.isInteger(quantity) || quantity <= 0) {
    throw new Error("quantity must be a positive integer")
  }

  return db.send(new TransactWriteCommand({
    ClientRequestToken: requestToken,
    ReturnConsumedCapacity: "TOTAL",
    TransactItems: [
      {
        Put: {
          TableName: "Cart",
          Item: { id: cartId, itemId, count: quantity },
          ConditionExpression: "attribute_not_exists(id)",
          ReturnValuesOnConditionCheckFailure: "ALL_OLD",
        },
      },
      {
        Update: {
          TableName: "Items",
          Key: { id: itemId },
          UpdateExpression: "SET #count = #count - :quantity",
          ConditionExpression: "#count >= :quantity",
          ExpressionAttributeNames: { "#count": "count" },
          ExpressionAttributeValues: { ":quantity": quantity },
          ReturnValuesOnConditionCheckFailure: "ALL_OLD",
        },
      },
    ],
  }))
}

// Keep this same token and payload for retries of this business request.
await reserveItem("reservation-777-attempt-1", "777", "777-000", 1)

The condition compares the stored numeric attribute to a placeholder. The update subtracts from #count, the existing attribute, rather than from an undefined :count value. If stock is missing or insufficient, or the cart key already exists, neither action commits.

The v3 document client takes native values. TransactWriteCommand returns consumed capacity when requested, but does not have a successful-write ALL_NEW option. Read the required state afterward, or use TransactGetItems when you need a coherent multi-item result.

Python transaction with boto3

The low-level boto3 client takes DynamoDB JSON. Strings use S, numbers use N with a string representation, and each transaction action uses the same table and key names as the JavaScript example.

import boto3
from botocore.exceptions import ClientError

client = boto3.client("dynamodb")


def reserve_item(request_token, cart_id, item_id, quantity):
    if isinstance(quantity, bool) or not isinstance(quantity, int) or quantity <= 0:
        raise ValueError("quantity must be a positive integer")

    try:
        return client.transact_write_items(
            ClientRequestToken=request_token,
            ReturnConsumedCapacity="TOTAL",
            TransactItems=[
                {"Put": {
                    "TableName": "Cart",
                    "Item": {
                        "id": {"S": cart_id},
                        "itemId": {"S": item_id},
                        "count": {"N": str(quantity)},
                    },
                    "ConditionExpression": "attribute_not_exists(id)",
                    "ReturnValuesOnConditionCheckFailure": "ALL_OLD",
                }},
                {"Update": {
                    "TableName": "Items",
                    "Key": {"id": {"S": item_id}},
                    "UpdateExpression": "SET #count = #count - :quantity",
                    "ConditionExpression": "#count >= :quantity",
                    "ExpressionAttributeNames": {"#count": "count"},
                    "ExpressionAttributeValues": {":quantity": {"N": str(quantity)}},
                    "ReturnValuesOnConditionCheckFailure": "ALL_OLD",
                }},
            ],
        )
    except ClientError as error:
        if error.response["Error"]["Code"] == "TransactionCanceledException":
            for index, reason in enumerate(error.response.get("CancellationReasons", [])):
                print(index, reason.get("Code"), reason.get("Message"))
        raise
import boto3
from botocore.exceptions import ClientError

client = boto3.client("dynamodb")


def reserve_item(request_token, cart_id, item_id, quantity):
    if isinstance(quantity, bool) or not isinstance(quantity, int) or quantity <= 0:
        raise ValueError("quantity must be a positive integer")

    try:
        return client.transact_write_items(
            ClientRequestToken=request_token,
            ReturnConsumedCapacity="TOTAL",
            TransactItems=[
                {"Put": {
                    "TableName": "Cart",
                    "Item": {
                        "id": {"S": cart_id},
                        "itemId": {"S": item_id},
                        "count": {"N": str(quantity)},
                    },
                    "ConditionExpression": "attribute_not_exists(id)",
                    "ReturnValuesOnConditionCheckFailure": "ALL_OLD",
                }},
                {"Update": {
                    "TableName": "Items",
                    "Key": {"id": {"S": item_id}},
                    "UpdateExpression": "SET #count = #count - :quantity",
                    "ConditionExpression": "#count >= :quantity",
                    "ExpressionAttributeNames": {"#count": "count"},
                    "ExpressionAttributeValues": {":quantity": {"N": str(quantity)}},
                    "ReturnValuesOnConditionCheckFailure": "ALL_OLD",
                }},
            ],
        )
    except ClientError as error:
        if error.response["Error"]["Code"] == "TransactionCanceledException":
            for index, reason in enumerate(error.response.get("CancellationReasons", [])):
                print(index, reason.get("Code"), reason.get("Message"))
        raise

Handle the raised error at the workflow boundary. A failed stock condition is a business outcome; a temporary conflict may merit a bounded retry. Do not expose full returned item images in public error messages.

Reading items in a transaction

TransactGetItems groups key-based reads. It cannot run a Query, scan a table or fetch through an index.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, TransactGetCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const result = await db.send(new TransactGetCommand({
  TransactItems: [
    { Get: { TableName: "Cart", Key: { id: "777" } } },
    { Get: { TableName: "Items", Key: { id: "777-000" } } },
  ],
  ReturnConsumedCapacity: "TOTAL",
}))
console.log(result.Responses)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, TransactGetCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const result = await db.send(new TransactGetCommand({
  TransactItems: [
    { Get: { TableName: "Cart", Key: { id: "777" } } },
    { Get: { TableName: "Items", Key: { id: "777-000" } } },
  ],
  ReturnConsumedCapacity: "TOTAL",
}))
console.log(result.Responses)

Responses correspond to the requested order; an absent item has no Item in its response entry. A transactional read does not reserve those versions for a later write. If the later transaction depends on them, include expected-state conditions, as explained in optimistic locking.

ClientRequestToken and retry safety

ClientRequestToken makes identical TransactWriteItems calls idempotent within a 10-minute window after the first request completes. A retry in that window with the same token and payload does not apply the writes again. Changing request parameters while retaining the token causes IdempotentParameterMismatchException.

Generate or assign the token once per logical request and retain the complete payload. Do not regenerate timestamps, random IDs or the token inside a retry loop. After the window expires, the token is treated as a new request, so it is not a permanent deduplication key.

For longer-lived duplicate protection, conditionally create an application idempotency item in the same transaction. Decide how long to retain it based on how long an old request may be replayed. The cart's create-only condition also rejects a second reservation using the same cart ID, but an existing cart does not by itself prove that a retry's payload matches the original request.

Error handling and CancellationReasons

TransactionCanceledException means the transaction did not commit. Its CancellationReasons list follows TransactItems order. An entry with code None means that action has no reported error; it does not mean the action committed independently. SDKs can expose diagnostic details differently, so handle a missing list without masking the original exception.

TransactionInProgressException is a request-level exception, not a cancellation reason for an individual action. Do not assume the SDK automatically retries all transaction cancellations. Monitor the TransactionConflict metric, throttle diagnostics, request latency and application conflict rates. AWS's transaction guide explains retry and capacity behavior.

Isolation levels and propagation

DynamoDB provides serializable isolation between transactional operations and individual standard item reads or writes. That does not turn a series of GetItem calls into one atomic multi-item read. One can run before a transaction and another after it, yielding a mixed view.

The interaction with Query, Scan and a BatchGetItem request considered as a group is read-committed. A BatchWriteItem group is likewise not an atomic transaction even though each individual write is atomic. Use TransactGetItems when those independently timed reads would violate your application's expectations.

After a transaction commits, its effects reach GSIs, Streams and backups progressively. Stream records from the same transaction can arrive separately or interleave with other records. Consumers must not assume a stream batch is a transaction boundary.

On MREC global tables, atomicity applies in the originating Region; other replicas can observe some changes before others replicate. MRSC tables reject transaction APIs. Neither mode provides a cross-Region transaction. The read consistency guide covers choosing a read path.

Transaction costs and best practices

DynamoDB performs preparation and commit work for transactional items. A transactional write of an item up to 1 KB consumes 2 write units; a transactional read of an item up to 4 KB consumes 2 read units. That is twice an ordinary write or strong read, and four times an eventual read. Round each item's size to its applicable unit boundary, and account for indexes and retries separately.

For three 500-byte write actions, one transaction consumes 6 write units before index costs. A canceled transaction can still consume capacity for attempted work. There is no separate transaction-enablement charge, but saying transactions have no additional cost would hide this extra capacity consumption.

Keep transactions as small as the business rule permits. Avoid placing unrelated updates in the same transaction, and avoid one frequently updated coordination item that makes otherwise independent requests conflict. Use the capacity calculator for item sizing. For independent bulk puts and deletes, BatchWriteItem is often more appropriate because atomic grouping is unnecessary.