> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.