update_google_sheets

update_google_sheets_row(
    sheet_id: str,
    data: dict,
    where: dict = None,
    row_number: int = None,
    expected: dict = None,
    sheet_name: str = None,
) -> dict

Patches only the named cells in exactly one existing row. It never rewrites untouched cells or changes the header row.

Select the row in one of two ways:

where={...} searches for an exact, unique match. This is the simplest option for sheets with up to 10,000 populated rows.
row_number=... plus expected={...} updates a row already returned by list_google_sheets_rows. This is efficient for larger sheets.

Parameters

Name	Type	Description
`sheet_id`	`str`	Spreadsheet ID from the Google Sheets URL
`data`	`dict`	Existing column names and their replacement values
`where`	`dict`	Exact values that must identify one unique row
`row_number`	`int`	One-based row number from a list result; row 1 is the header
`expected`	`dict`	Values that must still be present when using `row_number`
`sheet_name`	`str`	Optional tab name; defaults to the first tab

Provide either where, or both row_number and expected. Do not provide both selector forms.

Returns

{
    "success": True,
    "previousValues": {"Status": "Pending"},
    "row": {
        "rowNumber": 42,
        "values": {
            "Order ID": "1000123",
            "Status": "Cancelled",
        },
    },
}

Example: cancel one pending refund

def execute_action(context):
    order_id = context["args"]["orderId"]

    result = update_google_sheets_row(
        "YOUR_SHEET_ID",
        {"Status": "Cancelled"},
        where={
            "Order ID": order_id,
            "Status": "Pending",
        },
        sheet_name="Refunds",
    )

    return {
        "success": True,
        "rowNumber": result["row"]["rowNumber"],
    }

Matching the current status prevents an already processed request from being changed back accidentally. Include a unique request ID or conversation ID when an order can have more than one request.

Example: update a row from a paginated result

page = list_google_sheets_rows(
    "YOUR_SHEET_ID",
    sheet_name="Refunds",
    where={"Order ID": "1000123"},
)
row = page["rows"][0]

update_google_sheets_row(
    "YOUR_SHEET_ID",
    {"Status": "Cancelled"},
    row_number=row["rowNumber"],
    expected={
        "Order ID": row["values"]["Order ID"],
        "Status": row["values"]["Status"],
    },
    sheet_name="Refunds",
)

The expected values are re-read immediately before writing. If somebody sorts or edits the sheet after it was listed, the call returns a conflict instead of updating an unrelated row.

Failure behavior

No matching row: 404
More than one matching row: 409; add another unique match column
Expected values changed: 409; list the row again before deciding what to do
Unique-match search exceeds 10,000 populated rows: 422; list with cursors, then update by row_number and expected
Missing update or match column: 400

Prerequisites

Share the spreadsheet with [email protected] as an Editor. The target columns must already exist in the header row.