> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplace Hub

> Publish catalogs to the B2B marketplace, discover content from other brands, and subscribe to live catalog updates.

## Overview

The **Marketplace Hub** is a B2B content exchange where workspace owners can publish catalogs for other businesses to discover, clone, or subscribe to. It works both as a distribution channel (publisher perspective) and a content sourcing tool (consumer perspective).

***

## Publisher perspective

As a publisher, you expose your catalog to the marketplace ecosystem — whether for free or for a fee.

### Publishing a catalog

1. Ensure your catalog has completed at least the Silver pipeline stage
2. Navigate to the catalog → **Marketplace** tab
3. Configure visibility, pricing, and category
4. Click **Publish to Hub**

Once published, your catalog appears in the Hub browse feed and is searchable by name, category, and tags.

### Pricing models

| Model                 | Description                                                           |
| --------------------- | --------------------------------------------------------------------- |
| **Free**              | Catalog is freely cloneable and subscribable                          |
| **Paid (via Stripe)** | Consumers pay a one-time or recurring fee managed via Stripe Checkout |

Paid catalog access is gated at the API level — subscription status is verified on every clone and subscribe request.

### Catalog versioning

Every time you update a published catalog (add products, run Silver/Gold, edit metadata), a new **version** is created automatically. Versions are immutable snapshots.

| Version field | Description                              |
| ------------- | ---------------------------------------- |
| `version`     | Auto-incrementing integer (v1, v2, v3…)  |
| `createdAt`   | Timestamp of the version                 |
| `changeCount` | Number of products added/updated/removed |
| `publishedBy` | Member who triggered the publish         |

Subscribers receive a notification when a new version is available and can choose to sync on their schedule.

### Publisher analytics

Track catalog performance from the **Analytics** tab or via API:

* **Views** — how many times the catalog preview was opened
* **Clones** — total one-time copies made
* **Active subscribers** — workspaces with live subscriptions
* **Revenue** — total collected (for paid catalogs)

See [Publisher Analytics API](/api-reference/hub/publisher-analytics) for details.

### Unpublish / delist

To remove a catalog from the Hub:

1. Navigate to the catalog → **Marketplace** tab
2. Click **Unpublish**

Unpublishing immediately removes the catalog from the browse feed. Existing subscribers retain their local data but stop receiving new version notifications. Pending syncs are cancelled.

<Warning>
  Unpublishing does not delete subscriber data. Workspaces that have already cloned your catalog keep their local copy.
</Warning>

***

## Consumer perspective

As a consumer, you browse the Hub to discover catalogs, preview products, and either clone or subscribe.

### Browse and discover

The Hub browse page supports:

* **Search** by keyword (catalog name, brand, description)
* **Filter** by category, price (free/paid), minimum score
* **Sort** by: Popular, Recent, Optimization Score

Each catalog card shows: name, publisher, product count, category, average score, and subscriber count.

### Preview without committing

Every published catalog offers a **preview** of its first 10 products plus aggregate stats (total count, average score, top categories, top brands) — no clone required. Use preview to evaluate fit before subscribing.

### Clone — one-time copy

**Clone** creates a local snapshot of the catalog in your workspace. It does not establish an ongoing connection.

* All products are copied into a new catalog in your workspace
* You can edit, enrich, and redistribute freely
* No sync — you won't receive future updates from the publisher

### Subscribe — live sync

**Subscribe** creates a live link between your workspace and the publisher's catalog. When the publisher releases a new version, you are notified and can sync.

#### Sync strategies

| Strategy | Behavior                                                     |
| -------- | ------------------------------------------------------------ |
| `auto`   | New versions are automatically applied to your local catalog |
| `manual` | You review and approve each sync via the UI or API           |

#### Conflict resolution strategies

When a synced product has local edits that conflict with publisher updates, the conflict resolution strategy determines the outcome:

| Strategy        | Behavior                                                                    |
| --------------- | --------------------------------------------------------------------------- |
| `keep_local`    | Your local edits always win; publisher changes are discarded for that field |
| `accept_remote` | Publisher changes always win; your local edits are overwritten              |
| `manual_review` | Conflicts are queued for manual resolution — neither side auto-wins         |

<Tip>
  Use `manual_review` for high-value catalogs where local edits represent significant work (custom descriptions, pricing adjustments). Use `accept_remote` for raw supplier feeds where the publisher owns the data.
</Tip>

***

## Conflict resolution flow

```mermaid theme={null}
graph TD
    A["Publisher releases v5"] --> B["Subscriber receives notification"]
    B --> C{Sync strategy?}
    C -- auto --> D["Apply v5 immediately"]
    C -- manual --> E["Queued for review"]
    D --> F{Conflicts?}
    E --> F
    F -- keep_local --> G["Local edits preserved"]
    F -- accept_remote --> H["Publisher data wins"]
    F -- manual_review --> I["Conflict queue\n(UI or API resolution)"]
```

***

## Catalog versioning model

```mermaid theme={null}
graph LR
    P1["v1 (published)"] --> P2["v2 (published)"]
    P2 --> P3["v3 (published)"]
    P3 --> P4["v4 (current)"]
    P4 --> S1["Subscriber A\n(on v3)"]
    P4 --> S2["Subscriber B\n(on v4, auto-sync)"]
    P4 --> S3["Subscriber C\n(on v2, manual)"]
```

Each subscriber can be on a different version. Syncing always moves forward — you cannot roll back to a previous publisher version.

***

## Access control

| Action          | Who can do it               |
| --------------- | --------------------------- |
| Publish catalog | Workspace owner or admin    |
| Set pricing     | Workspace owner only        |
| View analytics  | Workspace owner or admin    |
| Unpublish       | Workspace owner only        |
| Clone/subscribe | Any authenticated workspace |
| Preview         | Anyone (public)             |

***

## Best practices

<AccordionGroup>
  <Accordion title="Run Silver before publishing">
    Consumers judge catalog quality by normalized data. Publish after Silver (and ideally Gold) to maximize discoverability and subscriber conversion.
  </Accordion>

  <Accordion title="Version your catalog intentionally">
    Each save to a published catalog creates a new version and notifies subscribers. Batch your edits and publish once rather than making many small changes.
  </Accordion>

  <Accordion title="Choose conflict resolution per use case">
    Set `keep_local` when your downstream team adds custom descriptions or pricing. Set `accept_remote` for supplier feeds you use verbatim.
  </Accordion>

  <Accordion title="Monitor analytics after publishing">
    High view counts with low clone rates indicate a mismatch between catalog metadata and content. Improve your title, description, and category tagging.
  </Accordion>
</AccordionGroup>