Developer notes

Manual product sync

The following details how the plugin handles product sync when manually triggered from the admin settings page. In general, this performs a full catalog sync and updates all products with the latest matching information to or from Square.

When triggered, a background job is created (in the form of a wp option) that contains:

• An array of product IDs to be synced (validated_product_ids). These are the products that have been set to "Sync to Square" in the product settings.
• An (empty) array of product IDs that have been processed (processed_product_ids). These are used to keep track of what's been completed, and display a percentage in the UI.
• An array of "steps" to be performed during the sync.

Each sync "step" performs a specific task within the larger sync job. Steps have a few common qualities:

• They will be performed in cycles until they are marked as "complete". Only then will the job move to the next step.
• They keep track of the product IDs that still need to be processed, and pick up where they left off in case of timeouts or other issues
• Any API requests that are performed have their responses stored, so if the step times out, it will resume by using that stored response until it's been fully processed

System of record: Square

Square SOR sync consists of a single step, represented in this method. The sync process is:

1. Perform a catalog ITEM search, limited to the number of items defined by WooCommerce\Square\Sync\Manual_Synchronization::get_max_objects_to_retrieve()
2. Loop through each returned item, and skip any items that aren't present at the configured location
3. Loop through each item's variations and check for a Woo product with a matching SKU using wc_get_product_id_by_sku()
   1. If the found product is a variation, get its parent instead
   2. Store the matching Square item IDs to the product
   3. Add the Woo product to an array of products to be updated locally
4. When all of the Square items have been looped, continue with processing the products
5. Loop through each matched product and update its data like name, price, and inventory

If there are more items in the Square catalog than the number we request, their API will return a cursor, which tells us to keep searching after processing all matched products. As long as a cursor is present, we know that there are more items so the job step is not marked as "complete". As soon as we get an API response with a blank cursor, we mark the sync as complete. We also log any products that weren't processed (because no match was found) as failed.

System of record: WooCommerce

Woo SOR sync is far more complex and consists of many steps. All operations are performed in batches, defined by WooCommerce\Square\Sync\Manual_Synchronization::get_max_objects_to_retrieve()

1. Gather and upsert all each product's top-level category
   1. extract_category_ids
   2. refresh_category_mappings
   3. query_unmapped_categories
   4. upsert_categories
2. Gather all products that already have Square ID meta set (update_matched_products)
   1. Batch retrieve these items
   2. Upsert all items that were found with their match Woo product's latest data
   3. All products that were found get marked as "processed" and won't be looked at further
   4. Any that weren't will be tried in the next step
3. Gather all products that have not yet been processed (search_matched_products)
   1. Batch search the catalog and find any Woo products with matching SKUs
   2. Upsert all items that were found with their match Woo product's latest data
   3. All products that were found get marked as "processed" and won't be looked at further
   4. Any that weren't will be upserted as new products in the next step
4. Gather all products that have not yet been processed (upsert_new_products)
   1. Batch upsert new Square items with the Woo product data
   2. Add the processed products to a inventory_push_product_ids array for the next step
5. Gather all products that need their inventory pushed (push_inventory)
   1. Send batch requests to update the item inventories
6. Sync complete

Interval polling

In addition to the full manual sync, the plugin also polls the Square catalog for item updates every hour (by default).

This interval can be customized using the wc_square_sync_interval (value in seconds).

Both systems of record

In both cases, when the scheduled poll action is triggered:

1. Batch retrieve inventory counts with the updated_after param set to the last poll. This will return only inventory counts that have changed since the last poll was run.
2. For each count object that is IN_STOCK (some may have other statuses), we retrieve the associated product based on the item's Square ID
3. Update the product's stock quantity to the new in-stock value

System of record: Square

In addition to the inventory update above, the polling job will also pull the latest product data when Square is SOR.

1. Search the catalog for items using the begin_time param, which will return only items that have changed since the last poll job was run.
2. Loop through the returned objects and try and find a Woo product based on the Square ID
3. If found, update the Woo product's data based on the latest Square data