# Reverb OpenCart Integration

An OpenCart 3.x extension that synchronises your product catalogue with your [Reverb.com](https://reverb.com/au) marketplace — keeping stock, pricing, product details, images, and orders in sync automatically.

---

## Features

- **Bidirectional sync** — push products from OpenCart to Reverb and pull updates back
- **Order import** — Reverb orders are imported as OpenCart orders (manual trigger or cron)
- **Selective sync** — choose which categories are eligible, with a per-product on/off toggle
- **Image sync** — product images are included in Reverb listings automatically
- **Price & stock sync** — changes on either platform propagate to the other
- **Category mapping** — map each OpenCart category to the correct Reverb category, with grouped dropdowns organised by root category
- **Per-product settings** — set condition (Mint, Excellent, Good, etc.), category override, handmade flag, and UPC/EAN exemption per product
- **Webhook support** — real-time updates from Reverb via webhook endpoint
- **Cron fallback** — scheduled polling when webhooks are not available
- **Sync log** — full activity log visible in the admin panel

---

## Requirements

| Requirement     | Version                          |
|-----------------|----------------------------------|
| OpenCart        | 3.x (tested on 3.0.3.x)          |
| PHP             | 7.4 or higher (8.1+ preferred)   |
| cURL            | Enabled                          |
| Reverb Account  | Seller account with API access   |

---

## File Structure

```text
upload/
├── admin/
│   ├── controller/extension/module/reverb.php
│   ├── language/en-gb/extension/module/reverb.php
│   ├── model/extension/module/reverb.php
│   └── view/template/extension/module/
│       ├── reverb.twig             (settings page)
│       └── reverb_product.twig    (per-product Reverb tab)
├── catalog/
│   └── controller/extension/module/reverb.php
└── system/
    └── library/reverb/
        ├── ReverbApi.php
        ├── ProductMapper.php
        └── OrderMapper.php
install.xml
reverb.ocmod.zip
```

---

## Installation

1. In your OpenCart admin, go to **Extensions > Installer** and upload `reverb.ocmod.zip`.
2. Go to **Extensions > Modifications** and click **Refresh**.
3. Go to **Extensions > Extensions**, select **Modules**, find **Reverb Integration**, click **Install**, then **Edit**.

---

## Configuration

### 1. API Token

1. Log in to [reverb.com/au](https://reverb.com/au) and go to **Account Settings > API Keys**.
2. Generate a personal access token with the scopes: `read_listings`, `write_listings`, `read_orders`.
3. Paste it into the **API Token** field in the Reverb module settings and save.

### 2. Sync Direction

| Option                       | Behaviour                                                                     |
|------------------------------|-------------------------------------------------------------------------------|
| One-way (OpenCart -> Reverb) | Products are pushed to Reverb only; changes on Reverb are ignored             |
| Both ways                    | Changes on either platform sync to the other; Reverb orders are also imported |

### 3. Shipping Rates

Set a flat AU domestic rate and an optional international rate. These are applied to all Reverb listings. Set to `0` for free shipping.

### 4. Category Mapping

Select which OpenCart categories are eligible for sync in the **Settings** tab. Then switch to the **Category Mapping** tab and map each selected category to the corresponding Reverb category. Categories are grouped by root (e.g. Guitars, Amps, Effects) for easy navigation.

### 5. Per-Product Settings

On each product's edit page a **Reverb** tab appears. Options:

- **List on Reverb** — enable/disable sync for this product
- **Condition** — required by Reverb (Mint, Excellent, Good, etc.)
- **Reverb Category** — override the category mapping for this product (optional)
- **Handmade** — check if the item is handmade or custom-built
- **UPC / EAN** — declare whether the item has a barcode or is exempt

Once synced, the Reverb listing ID and a direct link to the listing appear on this tab.

### 6. Order Import

Click **Import Orders from Reverb** on the Settings page to pull new Reverb orders into OpenCart. Each order is recorded in `oc_reverb_order_map` to prevent duplicates. Subsequent imports only fetch orders updated since the last run.

---

## Sync Behaviour

| Field          | OpenCart → Reverb | Reverb → OpenCart |
|----------------|:-----------------:|:-----------------:|
| Name / Title   | ✓                 | ✓                 |
| Description    | ✓                 | ✓                 |
| Price          | ✓                 | ✓                 |
| Stock / Qty    | ✓                 | ✓                 |
| Images         | ✓                 | —                 |
| Orders         | —                 | ✓                 |

---

## Webhooks

Register a webhook in your Reverb seller account pointing to:

```text
https://your-store.com/index.php?route=extension/module/reverb/webhook
```

Supported events: `listing/update`, `order/create`.

To verify webhook signatures, set a secret in Reverb and store it in `oc_setting` as `module_reverb_webhook_secret`.

---

## Cron (Polling Fallback)

Add this URL to your server's cron scheduler (recommended: every 15–30 minutes):

```text
https://your-store.com/index.php?route=extension/module/reverb/cron&cron_token=YOUR_TOKEN
```

Set `module_reverb_cron_token` in `oc_setting` to match.

---

## Database Tables

| Table                    | Purpose                                                               |
|--------------------------|-----------------------------------------------------------------------|
| `oc_reverb_product_map`  | Links OC products to Reverb listing IDs; stores per-product settings  |
| `oc_reverb_order_map`    | Tracks imported Reverb orders to prevent duplicates                   |
| `oc_reverb_sync_log`     | Records every push/pull operation with status and error detail        |

---

## Development

See [CLAUDE.md](CLAUDE.md) for full technical architecture, API endpoint reference, field mapping details, and developer guidelines.

---

## License

MIT