Two-Way Sync
How edits made in Google Sheets reach your WordPress site: the two ways to receive them, what changes in WordPress, including WooCommerce orders and products, setup, security and limits.
Maintained by Arden Talbot, founder of SheetLinkWP
What it does
SheetLink's default direction is one-way: a form submission lands in your Google Sheet. Two-Way Sync adds the reverse path. When someone edits a row in the sheet, the plugin is told which row changed and what it now contains.
What happens next is deliberately narrow:
- The edit is listed under Recent incoming updates on the Two-Way Sync screen. The last 50 are kept.
- The plugin fires the
sheetlinkwp_sheet_updateaction with the row, so your own code can act on it. - If you use the Lead Inbox with the one-click Google connection, a change to a lead's status or owner in the sheet is applied to that lead.
- From SheetLink Pro 1.3.0, if you use WooCommerce Sync and switch it on, an edit to the status cell of an order row changes the order's status, and an edit to a price or stock cell of a product row changes the product. See Changing WooCommerce from the sheet below.
That is all it changes in WordPress. It does not edit form entries, posts or users. If you want one of those to follow the sheet, a developer hooks the action and writes that step.
Two-Way Sync is part of SheetLink Pro and needs a Pro or Agency licence. It works with Google Sheets only, not Excel.
Two ways to receive edits
Which one your site uses depends on how it is connected to Google.
One-click Google connection: a scheduled check. SheetLink Pro reads the connected spreadsheet through the Google Sheets API, compares each row with what it saw on the previous check, and reports the rows that changed. Nothing is installed in the sheet. The check runs every 60 seconds at the earliest and covers the first 500 rows under the header of each tab it watches. WordPress runs scheduled tasks when someone visits the site, so on a quiet site the check can run later than that. The first check only records the sheet and reports nothing.
It watches the tab chosen on the Google Sheets screen. When the Lead Inbox keeps lead status in the sheet, it also watches the tab of every rule.
Apps Script: each edit as it is made. You paste a small script into the sheet. When a cell is edited, the script sends the whole row to SheetLink's relay at sheetlinkwp.com. The relay checks the licence and passes the row on to your site's REST endpoint, /wp-json/sheetlinkwp/v1/sheet-update. Use this for a sheet that is not in the connected Google account, or when you want edits to arrive without waiting for the next check.
With the Apps Script method the edited row passes through SheetLink's relay on its way to your site. The relay does not keep the row; it counts the request against the licence. With the one-click connection your site reads the sheet from Google directly.
What the Lead Inbox does with an edit
This applies when the site uses the one-click Google connection, SheetLink Pro is active, and Google Sheet status sync is ticked in Lead Settings.
- A change in the status column (heading
Lead Statusunless you renamed it) sets the lead's status. The value has to be New, Contacted, Qualified, Won, Lost or Spam. Anything else is ignored and noted in the lead's activity. - A change in the assigned-to column (heading
Assigned Tounless you renamed it) sets the lead's owner. The value has to match one WordPress user by email address, login or display name. Clearing the cell removes the owner.
Each change is recorded in the lead's activity. It works the other way too: changing a lead's status or owner in WordPress writes it to the lead's row in the sheet.
Changing WooCommerce from the sheet
WooCommerce Sync writes a row to your sheet for each order and product event. From SheetLink Pro 1.3.0, Two-Way Sync can carry an edit made to one of those rows back to WooCommerce. Three kinds of change are available, and each is off until you switch it on under SheetLink -> WooCommerce Sync -> Changes made in the sheet.
- Order status. Edit the
statuscell of an order row and the order moves to that status. Type it as WooCommerce names it, for examplecompletedoron-hold; the label, such as On hold, works too. You choose which statuses the sheet may set. Processing, on-hold and completed are allowed to begin with. - Product price. Edit the
regular_priceorsale_pricecell of a product row. Write a plain number such as 12.50. Anything else, including 12,50, is refused rather than guessed at. A sale price has to be lower than the regular price, and emptying the cell ends the sale. Thepricecolumn is the price WooCommerce works out from the other two, and it is not read. - Product stock. Edit the
stock_quantitycell of a product row with a whole number. The product must have stock tracking switched on in WooCommerce.
Only the cell you edit is acted on. One order has several rows in the sheet (created, completed, refunded), each holding the status the order had at that moment. Typing a note into an older row does not send its old status back to WooCommerce.
What it needs:
- The Apps Script method, with script version 2 from the Two-Way Sync screen. The script says which cell was edited. The scheduled check of the one-click connection does not, so it cannot make these changes. A sheet still running the earlier script is ignored, and the WooCommerce Sync screen says so.
- The
_sheetlink_wc_eventcolumn and theorder_idorproduct_idcolumn, left in the sheet. They are how a row is matched to its order or product. - If the row has an
emailcolumn (orders) or askucolumn (products), its value has to match the order or product with that id. A row that does not match is refused.
What to expect:
- WooCommerce treats a status change from the sheet as it treats one made on the order screen: it sends its usual emails to the customer and adjusts stock.
- Setting an order to Refunded records a refund in WooCommerce. It does not send money back through the payment gateway.
- A variable product's price cannot be set this way, because its variations are not sent to the sheet.
- Completing an order adds an Order completed row, and a price or stock change adds a Product updated row, if those events are switched on. Moving an order to any other status adds no row.
- The WooCommerce Sync screen lists the last 20 edits: what was applied, and what was refused and why.
Prerequisites
- SheetLink Forms and SheetLink Pro installed and active
- An active Pro or Agency licence
- A Google Sheet that already receives form submissions from SheetLink
- For the Apps Script method: Two-Way Sync switched on under SheetLink -> Features, and permission to add a script and a trigger to that sheet
Setup with the one-click Google connection
- Connect Google on the Google Sheets screen if you have not already.
- Switch on Two-Way Sync under SheetLink -> Features and open SheetLink -> Two-Way Sync. Under How this site receives edits it shows Google sync active, how often it checks, when the next check is due and when it last read the sheet.
- Edit a cell below the header row. After the next check the edit appears under Recent incoming updates.
The scheduled check itself does not depend on that switch. It runs whenever Google is connected and the licence includes Two-Way Sync; the switch adds the screen where you can see it.
Setup with the Apps Script
- Switch on Two-Way Sync under SheetLink -> Features and open SheetLink -> Two-Way Sync. The Apps Script section shows a script generated for your licence.
- Open the Google Sheet that receives your form submissions. Click Extensions -> Apps Script.
- Replace the contents of the
Code.gsfile with the script copied from the Two-Way Sync screen and save. - Click the triggers icon in the left sidebar (the small clock). Click Add Trigger and choose: function =
onEdit, event source = From spreadsheet, event type = On edit. Authorize when prompted. - Edit any cell below the header row. The edit appears under Recent incoming updates.
The script on the screen is version 2 (SheetLink Pro 1.3.0). It also says which cell was edited, and it sends every row of a paste or fill-down, up to 20, where the earlier script sent only the first. If an earlier script is in your sheet, replace its code with the current one and save. The trigger you added stays as it is.
Security model
This applies to the Apps Script method, where requests reach your site from outside.
- At the relay. The script sends your site's licence token. The relay accepts the request only if that token belongs to an active activation whose licence includes Two-Way Sync, and it forwards to the site that token was activated on, nowhere else. It accepts at most 120 requests a minute per licence.
- Signed forwarding. The relay signs each forwarded request with HMAC-SHA256 over a timestamp and the request body, using a key derived from the licence token. The plugin recomputes the signature and rejects a request whose timestamp is more than five minutes off. For older plugin versions the relay also sends a shorter shared secret, and the plugin accepts either one unless you define
SHEETLINK_TWOWAY_REQUIRE_HMACastrueinwp-config.php, which makes the signature mandatory. - At your site. The endpoint answers 403 unless the licence includes Two-Way Sync. After ten failed attempts from one address within five minutes, further requests from that address are refused until the five minutes have passed.
The signing key and the shared secret are both derived from the licence token, so the relay and your site can each compute them. The token is written into the script, so anyone who can edit the sheet can read it. Give edit access to the sheet with that in mind.
Echo suppression - avoiding edit loops
When SheetLink writes a row to the sheet, that write must not come back as an edit.
- Apps Script method. The plugin keeps a fingerprint of each row it sends for 60 seconds. An incoming edit with the same values is dropped: no log entry and no action. The order of the columns does not matter. A fingerprint is used once, so a second identical edit goes through.
- One-click connection. After writing a row the plugin reads it back and stores it as the last known state, so the next check sees no change.
Reacting to edits - the sheetlinkwp_sheet_update hook
For developers: the plugin fires a sheetlinkwp_sheet_update action for every edit that is not suppressed. Hook into it to apply your own logic. SheetLink's own bookkeeping columns (_sheetlink_ping, rule_id, ping_at) are removed from the row first.
add_action( 'sheetlinkwp_sheet_update', function ( $sheet_id, $row, $data ) {
// $sheet_id - the Google Sheet ID (spreadsheet)
// $row - 1-indexed row number that was edited
// $data - column heading => value for the whole row
// Example: when a lead is marked 'closed-won' in the Sheet, fire a
// confirmation email and stamp the WP user with the deal value.
if ( ( $data['Status'] ?? '' ) === 'closed-won' ) {
$email = sanitize_email( $data['Email'] ?? '' );
$value = (int) preg_replace( '/[^0-9]/', '', $data['Deal Value'] ?? '0' );
do_my_post_close_workflow( $email, $value );
}
}, 10, 3 );With the Apps Script method the action runs inside the REST request, and the relay waits 10 seconds for your site to answer. An edit that is not answered in time is not sent again, so put slow work in wp_schedule_single_event() or a queue rather than in the listener.
With the one-click connection the action runs inside the scheduled check and fires for the tab chosen on the Google Sheets screen. For the other watched tabs use sheetlink_sheet_row_changed, which passes the same three values plus the tab name.
From SheetLink Pro 1.3.0 a second action, sheetlink_two_way_row_edited, fires straight after sheetlinkwp_sheet_update for an edit received from the Apps Script. It passes a fourth value: the headings of the cells that were edited in that row and, for a single cell, the value it held before. That value is null when the sheet runs the earlier script. Use this action when a change should be applied only if a particular cell was edited, because the row always carries every column.
Limits
- Google Sheets only. Excel workbooks are not read.
- The whole row is passed. You cannot pick columns; your code reads the ones it needs.
- Scheduled check: the first 500 rows under the header of each watched tab.
- Scheduled check: rows are compared by row number, so inserting or deleting a row makes the rows below it count as changed.
- Scheduled check: a row that has been emptied is not reported.
- Apps Script method: an edit your site does not answer within 10 seconds is not sent again.
- Apps Script method: a paste or fill-down is sent one row at a time, up to 20 rows for one edit.
- WooCommerce changes from the sheet need the Apps Script method with script version 2. The scheduled check cannot make them.
Troubleshooting
Recent incoming updates stays empty (one-click connection). The check runs on WordPress's scheduler, which runs when someone visits the site. When a check is waiting, the screen shows due now (runs on the next visit to your site). Load any page of the site, or run wp-cron.php from a real cron job. Remember that the first check only records the sheet.
Recent incoming updates stays empty (Apps Script). Open the Apps Script editor, switch to the Executions tab, and look for failed onEdit runs. The most common cause is a trigger that was never authorised: add the trigger again and accept the prompt.
The endpoint answers 403. The licence or the token in the script was not accepted. Check the licence on the SheetLink -> License page, then copy the script from the Two-Way Sync screen again so that it carries the current token.
An edit seems to be ignored. With the Apps Script method, an incoming edit whose values equal a row the plugin sent in the last 60 seconds is treated as the plugin's own write and dropped. An edit that only touches SheetLink's bookkeeping columns is skipped as well.
The Two-Way Sync menu does not appear. It appears when SheetLink Pro is active, the licence includes Two-Way Sync (Pro or Agency) and Two-Way Sync is switched on under SheetLink -> Features.
Ready to Get Started?
Install SheetLink Forms and connect your first form in under 10 minutes.
