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

# Pools API: manage reusable network and merchant sets

> Create named sets of networks and merchants. Pass a pool_id to search endpoints to automatically scope results without repeating filter lists on every request.

The Pools API lets you define a reusable set of networks and merchants once, then reference it by ID across search endpoints. Instead of passing the same `network_ids` and `merchant_ids` on every request, you attach a `pool_id` and the API resolves the filters automatically.

## How pools work

A pool stores:

* **Networks** — affiliate networks to include
* **Merchants** — merchants to include in results

When you pass `pool_id` to a supported search endpoint, the pool's networks and merchants are combined with any explicitly passed filter values — not replaced.

<Warning>
  Pools are team-scoped. Passing a `pool_id` that belongs to a different team returns a `422` error.
</Warning>

## Using a pool in search

Pass `pool_id` as a top-level parameter to any of these endpoints:

| Endpoint                       | Description                                                                            |
| ------------------------------ | -------------------------------------------------------------------------------------- |
| `POST /v1/products`            | Search affiliate products                                                              |
| `POST /v1/products/omni`       | Unified product search                                                                 |
| `POST /v1/promotions`          | Search promotions                                                                      |
| `GET /v1/merchants?extended=1` | List merchants — different semantics, see [below](#using-a-pool-with-get-v1-merchants) |

```json theme={null}
{
  "pool_id": "01JPSEEDP1ATA11P0010000100",
  "search": "shoes"
}
```

Pass the **bare** ULID — the `pool_`-prefixed `object_id` form returns `422`. Only one `pool_id` may be passed per request. Returns `422` if the id is prefixed, the pool does not exist, or it belongs to another team.

### Using a pool with `GET /v1/merchants`

`pool_id` behaves differently here than on products/omni/promotions — it's a hard scope rather than a filter merge, and it also decides whose credentials build `providers[]` links. Requires `extended=1`.

```bash cURL theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?extended=1&pool_id=01JPSEEDP1ATA11P0010000100' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

|                     | Products / Omni / Promotions                                                                   | Merchants (`extended=1`)                                                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What `pool_id` does | Combines the pool's `networks`/`merchants` with any `network_ids`/`merchant_ids` you also pass | Restricts the results to **only** the merchants collected into that pool — there's no separate `merchant_ids` param here to merge with                                                   |
| Effect on links     | N/A                                                                                            | Also decides whose network credentials (**Pools → Sources**) resolve `providers[].url`/`template`/`outclick` and approval status **first** — account-level credentials remain a fallback |
| Omitted             | No scoping applied                                                                             | No scoping applied; link/approval resolution falls back to your account's **default pool**                                                                                               |

<Tip>
  Running more than one pool — separate credentials per site or brand, say? Pass the `pool_id` that matches the request; a Source configured on one pool never applies to a different pool's request. This is **not** provider isolation, though — for a provider the pool owns no credential for, resolution falls back to your account-level credential, so links can still come back with a different campaign than a pool that owns its own. See [Monetizing with the Merchants API](/guides/monetize-with-merchants#7-pools) for a full worked example.
</Tip>

## Available endpoints

| Method   | Endpoint                            | Description                     |
| -------- | ----------------------------------- | ------------------------------- |
| `GET`    | `/v1/pools`                         | List all pools                  |
| `POST`   | `/v1/pools`                         | Create a pool                   |
| `GET`    | `/v1/pools/{id}`                    | Get a pool                      |
| `PUT`    | `/v1/pools/{id}`                    | Update a pool                   |
| `DELETE` | `/v1/pools/{id}`                    | Delete a pool                   |
| `GET`    | `/v1/pools/{id}/settings`           | Get pool settings               |
| `PATCH`  | `/v1/pools/{id}/settings`           | Update pool settings            |
| `POST`   | `/v1/pools/{id}/networks`           | Add networks to a pool          |
| `DELETE` | `/v1/pools/{id}/networks`           | Remove networks from a pool     |
| `PUT`    | `/v1/pools/{id}/networks/{network}` | Update network affiliate config |
| `POST`   | `/v1/pools/{id}/merchants`          | Add merchants to a pool         |
| `DELETE` | `/v1/pools/{id}/merchants`          | Remove merchants from a pool    |