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

# List storefronts

> List buyer-visible storefronts with canonical availability

`GET /api/v2/buyer/storefronts`

Lists storefronts visible to the buyer as compact summary rows. Each row carries canonical transaction readiness plus scalar buyer-connection counts instead of source-level detail. A listed storefront can still be unavailable while its seller finishes setup. Fetch a single storefront for rolled-up connection state, or fetch storefront capabilities for source-level diagnostic rows. Filterable and offset-paginated.

## Request

<CodeGroup>
  ```bash List theme={null}
  curl "https://api.apostra.com/api/v2/buyer/storefronts?limit=20" \
    -H "Authorization: Bearer $SCOPE3_API_KEY"
  ```

  ```bash Filter by name and channel theme={null}
  curl "https://api.apostra.com/api/v2/buyer/storefronts?name=premium&channel=ctv&limit=20" \
    -H "Authorization: Bearer $SCOPE3_API_KEY"
  ```
</CodeGroup>

## Parameters

| Field        | In    | Type    | Required | Notes                                                                                                                                  |
| ------------ | ----- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | query | string  | No       | Partial, case-insensitive seller, company, brand, storefront, publisher/brand domain, or website match                                 |
| `status`     | query | enum    | No       | Deprecated stored-control filter: `neutral`, `paused`, `configuring`, `transacting`, or `archived`. This is not transaction readiness. |
| `channel`    | query | string  | No       | ADCP channel the storefront carries (e.g. `display`, `ctv`)                                                                            |
| `region`     | query | string  | No       | Region code the storefront covers (e.g. `EMEA`, `NORAM`, `APAC`)                                                                       |
| `visibility` | query | enum    | No       | `public` (default) — marketplace-listed storefronts; `private` — all storefronts owned by the caller's parent org                      |
| `limit`      | query | integer | No       | Max per page (default 20, max 100)                                                                                                     |
| `offset`     | query | integer | No       | Pagination offset (default 0)                                                                                                          |

## Response

```json theme={null}
{
  "items": [
    {
      "id": 42,
      "platformId": "premium-ctv",
      "name": "Premium CTV Storefront",
      "publisherDomain": "premium-ctv.example.com",
      "displayStatus": "neutral",
      "readiness": {
        "canTransact": true,
        "effectiveStatus": "live",
        "blockerIds": []
      },
      "adapterProviderType": null,
      "supportedRoutingTypes": ["DECISIONED", "ROUTED"],
      "channels": ["CTV", "display"],
      "regions": ["US", "EMEA"],
      "sourceCount": 3,
      "connectedSourceCount": 1
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextOffset": null
}
```

| Field                               | Type            | Notes                                                                                                           |
| ----------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
| `items`                             | array           | Storefront summary rows                                                                                         |
| `items[].id`                        | integer         | Storefront ID                                                                                                   |
| `items[].platformId`                | string          | Public-facing slug                                                                                              |
| `items[].name`                      | string          | Storefront display name                                                                                         |
| `items[].publisherDomain`           | string \| null  | Publisher domain                                                                                                |
| `items[].displayStatus`             | enum            | Deprecated stored-control compatibility label. Do not use it for purchasing availability.                       |
| `items[].readiness.canTransact`     | boolean         | Canonical answer to whether ordinary buyer traffic may transact now                                             |
| `items[].readiness.effectiveStatus` | enum            | `archived`, `paused`, `blocked`, or `live`                                                                      |
| `items[].readiness.blockerIds`      | string\[]       | Machine-readable blocker IDs; empty when live                                                                   |
| `items[].adapterProviderType`       | string \| null  | Adapter platform (e.g. `meta`), `null` for non-adapter                                                          |
| `items[].supportedRoutingTypes`     | array           | Deprecated v2 compatibility placeholder. Always both legacy values; do not use for storefront type or behavior. |
| `items[].channels` / `regions`      | array           | Supported channels and covered regions                                                                          |
| `items[].sourceCount`               | integer         | Total inventory sources                                                                                         |
| `items[].connectedSourceCount`      | integer         | Sources the buyer is already wired to use. This is credential connection state, not readiness.                  |
| `total`                             | integer         | Total matching storefronts                                                                                      |
| `hasMore`                           | boolean         | Whether more pages exist                                                                                        |
| `nextOffset`                        | integer \| null | Offset for the next page, or `null`                                                                             |

## Errors

* `400 VALIDATION_ERROR` — invalid `status`/`visibility` enum or out-of-range `limit`.
* `401 UNAUTHORIZED` — missing or invalid bearer token.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Storefront tasks" href="/v2/buyer/storefronts/tasks" icon="list-check">
    All storefront operations
  </Card>

  <Card title="Get storefront" href="/v2/buyer/storefronts/tasks/get-storefront" icon="magnifying-glass">
    Rolled-up connection state
  </Card>

  <Card title="Get storefront capabilities" href="/v2/buyer/storefronts/tasks/get-storefront-capabilities" icon="signal">
    Source-level capability diagnostics
  </Card>

  <Card title="Storefront object guide" href="/v2/object-guides/storefront" icon="store">
    Full model: sources, OAuth, seller side
  </Card>
</CardGroup>