Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/johnoconnor0/hubspot-x-woocommerce-integration


https://github.com/johnoconnor0/hubspot-x-woocommerce-integration

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

          
# HubSpot WooCommerce Sync



**Version:** 1.0.0

**Author:** [Weblifter](https://weblifter.com.au)

**Plugin URI:** [GitHub Repository](https://github.com/weblifter/hubspot-woocommerce-sync)

**License:** GPL-3.0



## Overview



HubSpot WooCommerce Sync is a WordPress plugin that integrates WooCommerce with HubSpot, allowing store owners to **automatically sync orders as deals in HubSpot CRM**. This plugin uses a **public HubSpot app** to authenticate users and store their API tokens.



---



## Features



* **HubSpot OAuth Authentication**

  Securely connect your WooCommerce store to HubSpot using OAuth 2.0. Tokens are managed automatically and refreshed when needed. The connection is initiated via the admin settings panel and validated via the HubSpot API.



* **Automatic Deal Creation for Online Orders**

  When an online WooCommerce order is paid (via `woocommerce_payment_complete`), the plugin creates a corresponding **HubSpot Deal** in the selected pipeline. The deal includes:



  * Order total and shipping costs

  * Full billing and shipping details

  * Contact association (customer email, phone, name)

  * Optional company association

  * Line items as HubSpot products (with price, quantity, GST, SKU)

  * Deal notes from WooCommerce's customer note field

  * PayWay transaction reference, if available

  * Pipeline and stage mappings from WooCommerce order status. Each status can

    be mapped separately for the **Online Orders Pipeline** and the

    **Manual Orders Pipeline** using the `hubspot-online-mapping` and

    `hubspot-manual-mapping` options.



* **Automatic Order Completion**

  Online orders can be marked **complete** automatically when enabled in the **Orders** tab.



* **Order Cleanup**

  Automatically delete orders that remain in a chosen status (e.g., Pending Payment) for a specified number of days. These controls live in the **Orders** tab.



* **Manual Deal Creation**

  For unpaid or offline WooCommerce orders, admins can click **"Create Deal"** in the Order Management screen. These orders are pushed to the pipeline chosen for manual sales and use the stage mappings defined under **Manual Orders Pipeline**.



* **Manual Order Sync from HubSpot Deal**

  Orders created manually in WooCommerce can be fully re-synced from their associated HubSpot deal using the **"Sync"** button. This updates:



  * Billing/shipping fields

  * Customer contact info

  * Line items

  * Deal stage and pipeline labels



* **Deal Stage Updates**

  At key moments, the plugin updates the **HubSpot deal stage** using admin-defined mappings.



* **WooCommerce Admin Order Management UI**

  A powerful admin screen at **HubSpot -> Order Management** allows you to:



  * Filter/search orders by status or customer name

  * View order status

  * Trigger actions: **Create Deal**, **Sync from HubSpot**

  * See whether an order is "Manual" or "Online"



* **PayWay Integration Support**

  Automatically syncs `_payway_api_order_number` to the **HubSpot Deal** after payment. Ensures external transaction references are tracked.



* **Smart Order Typing (Manual vs Online)**



  * Admin-created, REST API, and CLI orders are marked as `manual`

  * Frontend WooCommerce checkout orders are marked as `online`

  * This distinction controls pipeline/stage logic



* **Stage & Pipeline Label Caching**

  Caches HubSpot pipeline and stage labels from the API to reduce repeated requests and provide readable names in the admin UI. Cached data lives in the `hubspot_cached_pipelines` option and can be refreshed from the **Pipelines** tab using the **Sync** button.



* **Robust Error Handling and Logging**



  * Errors during sync or API requests are logged via `error_log()` and `hubwoo_log()`

  * Invalid configurations (e.g., missing pipeline) now trigger order notes or error returns

  * Admin is alerted if deals aren't created due to missing mapping



* **Custom Line Item Integration**

  Each WooCommerce product is added to the HubSpot deal as a **line item** with:



  * Product name, quantity, subtotal, SKU, and tax

  * Proper associations via HubSpot v4 batch API



* **Extensibility for Developers**

  Clean separation of concerns across files:



  * `create-object.php`: Deal, contact, and company creation

  * `fetch-object.php`: Pulling HubSpot data

  * `manual-order-sync.php`, `online-order-sync.php`: Contextual sync flows



---



## Installation



### Manual Installation

1. Download the latest release from [GitHub](https://github.com/weblifter/hubspot-woocommerce-sync).

2. Upload the `.zip` file to WordPress via **Plugins -> Add New -> Upload Plugin**.

3. Activate the plugin.



### Using GitHub Updater

1. Install the [GitHub Updater](https://github.com/afragen/github-updater) plugin.

2. Add the repository URL in the GitHub Updater settings.

3. The plugin will now receive updates directly from GitHub.



## Setup & Authentication



### 1. Configure HubSpot Credentials



Add the following constants to your `wp-config.php` file (recommended):



```php

define('HUBSPOT_WC_CLIENT_ID', 'your-hubspot-client-id');

define('HUBSPOT_WC_CLIENT_SECRET', 'your-hubspot-client-secret');

define('HUBSPOT_WC_REDIRECT_URI', 'https://your-site.com/wp-json/hubspot/v1/oauth/callback');

```



Replace the values with your HubSpot public app credentials.



### 2. Connect to HubSpot



1. **Go to WordPress Admin -> HubSpot Sync**.

2. Click the **Connect HubSpot** button and follow the authorization flow.

3. Once authenticated, select a **pipeline for online orders** and a separate

   **pipeline for manual orders** under the **Pipelines** tab.

4. Map each WooCommerce order status to a HubSpot stage for both pipelines using

   the status table on that tab (stored in `hubspot-online-mapping` and

   `hubspot-manual-mapping`).

5. Enable **Automatic Deal Creation** to sync new orders.

6. In the **Orders** tab, enable **Auto-Complete Online Orders** to automatically mark paid orders complete.



### Admin-Created Orders

Orders created manually in WooCommerce are **not** synced automatically. After

creating an order in the admin, go to **HubSpot -> Order Management** and click

the **Create Deal** button to push the order to HubSpot.



## REST API Endpoints



The plugin provides the following API routes. All routes require an authenticated user with the `manage_options` capability. In practice, you must be logged in as an administrator when calling `/start-auth` and `/oauth/callback`. The **Connect HubSpot** link on the plugin settings page opens these routes for you so authentication is handled automatically:



### Start OAuth Authentication

`GET /wp-json/hubspot/v1/start-auth`



**Query Parameter:**

- `store_url` (required) - The WooCommerce store URL.



### OAuth Callback

`GET /wp-json/hubspot/v1/oauth/callback`



**Handles HubSpot's OAuth response and stores the API tokens.**



The previous connection status endpoint has been removed for security. Only

administrators can access the OAuth routes.



## Uninstallation

To remove the plugin:

1. Deactivate the plugin in WordPress.

2. Click "Delete" to remove all associated data.



## License

This plugin is licensed under **GPL-3.0**.



## Support & Contributions

For bug reports, feature requests, or contributions, visit the [GitHub Issues](https://github.com/weblifter/hubspot-woocommerce-sync/issues) page.