# Install Aha.is for WooCommerce

This guide is for the person who administers the store. You do not need to be a
developer. You need access to the WordPress admin and to the server that runs
the store.

Aha.is for WooCommerce connects your WooCommerce store to Aha. Aha sends you orders. Your
store keeps your products on Aha up to date.

---

## 1. Requirements

Check these points before you install the plugin.

| Item | Minimum | Why |
| --- | --- | --- |
| WordPress | 6.0 | The plugin uses the REST API of this version. |
| WooCommerce | 8.0 | The plugin creates orders with WooCommerce. |
| PHP | 7.4 | Older versions cannot run the plugin. |
| HTTPS | Required | Aha sends order data to your store. The connection must be encrypted. |
| Server cron | Recommended for low-traffic stores | The plugin checks the Aha connection and syncs products in the background. |

### Why the server cron matters

WordPress has a built-in scheduler. It is called WP-Cron. WP-Cron only runs
when a visitor opens a page. A quiet store gets few visitors. The scheduled work
then waits for hours.

Aha.is for WooCommerce uses the scheduler to check the connection and to sync products. If
the scheduler does not run, Aha does not learn about product and stock changes.
Aha can then sell an item that you no longer have.

Section 4 shows how to set up a real server cron. This step is recommended for
low-traffic stores. A store with regular visits can skip it. The Diagnostics
tab shows when Aha background jobs are waiting.

---

## 2. Install the plugin

1. Open the WordPress admin of your store.
2. Go to **Plugins → Add New**.
3. Search for **Aha.is for WooCommerce**.
4. Select **Install Now**.
5. Select **Activate**.

You can also install the plugin from a zip file. Download the zip file from the
plugin page on WordPress.org. Go to **Plugins → Add New**, select
**Upload Plugin**, select the zip file, and then select **Install Now**.

### The WooCommerce notice

The plugin needs WooCommerce. If WooCommerce is not active, the plugin shows
this notice:

> Aha.is for WooCommerce needs WooCommerce. Activate WooCommerce first.

The plugin then does nothing. It does not receive orders and it does not sync
products. Activate WooCommerce, then reload the admin page. The notice goes away.

The plugin does not change your WooCommerce settings, your products, or your
existing orders during the installation.

---

## 3. Connect the store

Go to **WooCommerce → Aha** and select **Connect with Aha**. Follow the steps
on screen. Aha links your store and issues the keys by itself. You do not enter
a base URL, a store code, a key id or a secret. Connect is the only way to set
up the store.

The **Settings** tab has one option, **Product sync**. It keeps your products
on Aha up to date. Aha can pause it for your store. The same tab also has
**Disconnect from Aha**.

### Connection test

On the **Diagnostics** tab, select **Check connection**. The plugin asks Aha
about this store and shows the answer.

- A success message means that Aha answered this store.
- A failure message tells you whether Aha could not be reached or the store was
  disconnected. Reconnect from the Connect page if the store was disconnected.
  Give the message to your Aha contact if the problem stays.

If the saved connection state cannot be read, the Connect page offers
**Start over**. It removes the saved connection. Then connect again.

---

## 4. Set up the server cron (recommended for low-traffic stores)

Do this step on the server, not in the WordPress admin. Ask your hosting
provider for help if you do not have shell access.

### Step 1: Switch off WP-Cron

Open `wp-config.php`. Add this line above the line that says
`/* That's all, stop editing! */`:

```php
define( 'DISABLE_WP_CRON', true );
```

### Step 2: Add the cron job

Add one line to the crontab of the user that owns the store files. Replace
`example.com` with the domain of your store.

```cron
* * * * * curl -s https://example.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1
```

This line runs the scheduler every minute.

If your host prefers the WP-CLI command, use this line instead. Replace the path
with the directory of your WordPress installation.

```cron
* * * * * cd /path/to/wordpress && wp cron event run --due-now > /dev/null 2>&1
```

### Step 3: Check the result

Go back to **WooCommerce → Aha** and open the **Diagnostics** tab. Look at the
health list and at the support export.

- **real_server_cron** says `configured` after you set `DISABLE_WP_CRON`.
- **queue_lag_seconds** must stay low. A number that grows over minutes means
  that the cron job does not run.

---

## 5. Verify the installation

The **Diagnostics** tab of the Aha page shows what the plugin reports about
itself. Check these items.

| Item | Expected value |
| --- | --- |
| Connection to Aha | `OK`, with "Last checked" and a time. If it shows "Not checked yet", select **Check connection**. |
| action_scheduler (support export) | `available` |
| queue_lag_seconds (support export) | a low number |
| real_server_cron (support export) | `configured` (recommended for low-traffic stores) |
| environment (support export) | `production` |

Your store also answers a health request from Aha. Aha uses it to see the
versions, the queue and the environment of your store. The health request is
signed with the Connect order key, so nobody else can read this information.

### Safe mode

The plugin protects you against a wrong site. It stops all work when one of
these is true:

- Your host marks the site as a staging site or a development site.
- The address of the site changed after the installation.

This state is called safe mode. In safe mode the plugin sends nothing to Aha and
refuses every order from Aha. The Aha page shows a red notice with the
reason.

Safe mode is correct behaviour on a copy of your store. A copy still holds your
secret. Without safe mode, the copy would send false information to Aha.

If safe mode appears on your live store, do these steps:

- The reason is `non_production_environment`: WordPress tells the plugin that
  the site is not a live site. WordPress reads this from the setting
  `WP_ENVIRONMENT_TYPE`. Look for it in `wp-config.php` first. Set it to
  `production` with `define( 'WP_ENVIRONMENT_TYPE', 'production' );`, or remove
  it. A value in `wp-config.php` overrides the server environment. If the
  setting is missing everywhere, WordPress uses `production`. Ask your host if
  you cannot change it.
- The reason is `site_url_changed`, or the Aha page shows "This website's
  address changed": the address of the site changed after the installation.
  Select **Start over**, and then connect again. If the page shows no
  **Start over**, contact Aha.

---

## 6. Troubleshooting

| Problem | Cause | What to do |
| --- | --- | --- |
| The Aha page shows "Safe mode is on" with the reason `non_production_environment`. | The setting `WP_ENVIRONMENT_TYPE` of this site is not `production`. Some hosts set it on staging sites. | Set `WP_ENVIRONMENT_TYPE` to `production` in `wp-config.php`, or remove it there. If it is not in `wp-config.php`, ask your host to change it in the server environment. Then reload the page. |
| The Aha page shows "This website's address changed", or "Safe mode is on" with the reason `site_url_changed`. | The address of the store changed after the installation. | Select **Start over**. Then connect again. If the page shows no **Start over**, contact Aha. |
| Aha reports that your store answers 401. | The store is not connected any more, or the clock of the server is wrong. | Reconnect from the Aha page. Then ask your host to check the server time. The plugin accepts a difference of 5 minutes at most. |
| Aha reports that your store answers 409. | The store is in safe mode. | See the first two rows of this table. Do the steps in the row that matches the Aha page. |
| Orders arrive, but product changes do not reach Aha. | The scheduler does not run. | Do section 4 again. Check the queue lag on the Diagnostics tab. |
| The queue lag number grows. | The cron job does not run, or it fails. | Ask your host to check the cron job and its output. |
| The plugin shows "Aha.is for WooCommerce needs WooCommerce". | WooCommerce is not active. | Activate WooCommerce. Then reload the admin page. |
| The support export shows `action_scheduler`: `missing`. | A plugin or the host disabled the WooCommerce scheduler. | Contact your host or your developer. Background work runs slower. |
| Check connection fails with a network error. | The store cannot reach the Aha address. | Ask your host whether the server can open outgoing HTTPS connections. |
| An order from Aha does not appear. | The store refused the order, or the order did not reach the store. | Open the **Diagnostics** tab. **Orders from Aha** shows failed orders. If there is no failed order, ask your Aha contact for the error code of the last attempt. The code names the cause, for example `unknown_sku`. |

For any problem that stays, send your Aha contact these three items:

1. The reason text from the Aha page.
2. The plugin log. Go to **WooCommerce → Status → Logs** and select the file
   with the source `aha-is-for-woocommerce-sync`.
3. The date and the time of the problem, with the time zone.

Do not send passwords or API keys.
