# 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 automatically created as OpenCart orders
- **Selective sync** — choose which categories are eligible, with a per-product on/off toggle
- **Image sync** — product images are uploaded to 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
- **Per-product condition** — set the Reverb condition (Mint, Excellent, Good, etc.) 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+ recommended) |
| 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
reverb.ocmod.xml
```

---

## Installation

1. Copy the contents of the `upload/` folder into your OpenCart root directory.
2. In your OpenCart admin, go to **Extensions > Installer** and upload `reverb.ocmod.xml`.
3. Go to **Extensions > Modifications** and click **Refresh**.
4. 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.
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 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.

### 5. Per-Product Toggle

On each product's edit page a **Reverb** tab appears. Enable **List on Reverb**, choose the item condition, and optionally override the Reverb category for that product. Once synced, the Reverb listing ID and a direct link appear here.

---

## Sync Behaviour

| Field | OpenCart → Reverb | Reverb → OpenCart |
| --- | :---: | :---: |
| Name / Title | ✓ | ✓ |
| Description | ✓ | ✓ |
| Price | ✓ | ✓ |
| Stock / Quantity | ✓ | ✓ |
| 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 sync settings |
| `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