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

# Marketplace

> List your program in the AgentRef marketplace so affiliates can discover and apply to it.

The AgentRef marketplace is a feature-flagged public directory where affiliates browse and apply to affiliate programs. Listing your program there gives you passive inbound reach – affiliates find you rather than waiting for your invites.

<Info>
  During the current closed beta, marketplace discovery is gated by AgentRef's `marketplace_public` flag. Public listing settings can still be prepared, but live discovery returns an empty closed-beta response until the marketplace is opened.
</Info>

## How it works

Programs listed as `public` appear in the marketplace with their commission rate, category, EPC (earnings per click), and conversion rate. Affiliates can filter by category, minimum commission, and performance metrics. When an affiliate applies, they either get auto-approved instantly (if your program has `autoApproveAffiliates: true`) or land in your pending applications queue for manual review.

<Info>
  A program must be fully set up – Stripe connected, tracking installed, and at least one active affiliate – before it becomes eligible for public listing.
</Info>

## List your program

<Steps>
  <Step title="Open program settings">
    In the dashboard go to **Programs**, select your program, then open **Settings > Marketplace**. Set visibility to **Public** and fill in a short description and category. Save.
  </Step>

  <Step title="Confirm eligibility">
    If your program is not yet fully ready, AgentRef will show which setup steps are incomplete. Fix those first – an incomplete program cannot appear publicly even if you set visibility to public.
  </Step>
</Steps>

You can also update marketplace settings via the programs API. Use `marketplaceStatus: "draft"` while preparing the listing, `marketplaceStatus: "public"` when it should appear publicly, or `marketplaceStatus: "private"` to hide it. Use `applicationAccess: "open"` for marketplace applications and `applicationAccess: "invite_only"` for invite-only programs.

## Managing applications

When an affiliate applies from the marketplace, the application appears in **Programs > \[Your Program] > Applications**. Each application shows the affiliate's name, their optional introductory message, and the date applied.

* **Auto-approved** – if your program has `autoApproveAffiliates: true`, the affiliate is added immediately and receives their affiliate link.
* **Pending review** – if auto-approve is off, approve, decline, or block the application from the dashboard or Applications API.

<Tip>
  Enabling `autoApproveAffiliates` reduces drop-off. Affiliates who apply and get an immediate link are far more likely to start promoting than those who wait for manual approval.
</Tip>

## API reference

### List marketplace programs

Returns publicly listed programs when `marketplace_public` is enabled. During closed beta, the endpoint returns an empty list with `meta.note: "closed_beta"`. Available to affiliate API keys (scope `marketplace:read`).

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/marketplace/programs?sort=epc&minCommission=20&limit=20" \
    -H "Authorization: Bearer ak_aff_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const result = await fetch(
    'https://www.agentref.co/api/v1/marketplace/programs?sort=epc&minCommission=20&limit=20',
    { headers: { Authorization: 'Bearer ak_aff_YOUR_KEY' } },
  ).then((r) => r.json());
  ```

  ```python Python theme={null}
  import httpx

  result = httpx.get(
      "https://www.agentref.co/api/v1/marketplace/programs",
      headers={"Authorization": "Bearer ak_aff_YOUR_KEY"},
      params={"sort": "epc", "minCommission": 20, "limit": 20},
  ).json()
  ```
</CodeGroup>

**Query parameters**

| Parameter         | Type   | Description                                           |
| ----------------- | ------ | ----------------------------------------------------- |
| `category`        | string | Filter by category (e.g. `saas`, `ecommerce`)         |
| `minCommission`   | number | Minimum commission percentage                         |
| `minEpc`          | number | Minimum earnings per click (USD)                      |
| `sort`            | string | `epc` \| `conversionRate` \| `commission` \| `newest` |
| `limit`           | number | Max results (1–50, default 20)                        |
| `page` / `offset` | number | Pagination                                            |

### Apply to a program

Submits an affiliate application. Requires an affiliate API key (scope `marketplace:apply`).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://www.agentref.co/api/v1/marketplace/apply/PROGRAM_ID" \
    -H "Authorization: Bearer ak_aff_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message": "I run a newsletter focused on SaaS tools with 8k subscribers."}'
  ```

  ```javascript JavaScript theme={null}
  const application = await fetch(
    'https://www.agentref.co/api/v1/marketplace/apply/PROGRAM_ID',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer ak_aff_YOUR_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message: 'I run a newsletter focused on SaaS tools with 8k subscribers.',
      }),
    },
  ).then((r) => r.json());
  ```

  ```python Python theme={null}
  application = httpx.post(
      "https://www.agentref.co/api/v1/marketplace/apply/PROGRAM_ID",
      headers={"Authorization": "Bearer ak_aff_YOUR_KEY"},
      json={"message": "I run a newsletter focused on SaaS tools with 8k subscribers."},
  ).json()
  ```
</CodeGroup>

The response includes a `status` field (`auto_approved` or `pending`) and a `nextSteps` array describing what the affiliate should do next.

<Warning>
  Applying twice to the same program returns the existing application rather than creating a duplicate. The HTTP response code will be `200` instead of `201` in that case.
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Invite Affiliates" href="/merchant-guide/invite-affiliates">
    Invite affiliates directly without waiting for marketplace applications.
  </Card>

  <Card title="Conversions" href="/merchant-guide/conversions">
    See how commissions are created when affiliates drive sales.
  </Card>
</CardGroup>