Transactions

Use POST /:transaction to run a group of write operations as one atomic unit—either every operation commits, or none of them do. Use a transaction when a partial result would leave your data in an inconsistent state: creating an order and decrementing stock, moving a balance between two accounts, or writing a record and its child records together.

Send an array of operations. They run in order, in a single database transaction.

await swell.post('/:transaction', [
  { method: 'post', url: '/products', data: { name: 'Chair', price: 40 } },
  { method: 'put', url: '/products/6812a1f4c0', data: { stock_level: 12 } },
  { method: 'delete', url: '/products/6812a1f4c1' },
]);

Each operation takes the following fields:

Reads are not allowed inside a transaction—a get operation is rejected before anything runs. Each operation is permission-checked on its own, the same as if you had sent it as a standalone request.

Put the collection in the transaction URL and the operations inherit it:

await swell.post('/:transaction/products', [
  { method: 'post', data: { name: 'Chair', price: 40 } },
  { method: 'put', url: '6812a1f4c0', data: { stock_level: 12 } },
]);

On success, the response is an array in the same order as the operations you sent. Each entry is what that operation would have returned on its own:

[
  { "id": "6812a1f4c2", "name": "Chair", "price": 40 },
  { "id": "6812a1f4c0", "name": "Desk", "stock_level": 12 }
]

Operations run one after another, not in parallel. Keep transactions small: they hold locks on every record they touch, so a long transaction makes conflicts more likely for everyone writing to the same records.

A failed transaction rolls back completely and returns a typed error:

{
  "error": {
    "message": "Transaction exceeded time budget",
    "code": "transaction_timeout",
    "status": 408
  }
}

When an operation fails, the error carries op_index, the zero-based position of the operation that caused the rollback:

{
  "error": {
    "message": "Product not found",
    "code": "transaction_op_failed",
    "status": 404,
    "op_index": 1
  }
}

Retry transaction_conflict and transaction_throttled with exponential backoff. The other errors will fail the same way again.

Nothing is dispatched while a transaction is running. Webhooks and app functions make HTTP calls that can't be rolled back, so they are held back until the transaction is known to have committed.

Subscribe to transaction.committed when you need to react to the group as a whole.

Every transaction writes a log entry with its outcome, operation count, and duration. View them with the Swell CLI:

swell logs --type transaction