# Storefronts

A storefront is a named shop under your account, slug, catalogue, and whether prices are
shown. List and retrieve them; create and edit stay in the dashboard. Amounts on the stats
roll-up are integer minor units (cents).

```
GET    https://api.worthypayments.com/v1/stores
GET    https://api.worthypayments.com/v1/stores/stats
GET    https://api.worthypayments.com/v1/stores/{id}
```

| Scope | Grants |
|-------|--------|
| `stores:read` | List, stats, and fetch storefronts |

`GET /v1/stores/stats` is declared **before** `GET /v1/stores/{id}` so `stats` is
never parsed as an id.

Related: [Products](./05-products.md) (catalogue items that live on a storefront),
[Checkout Links](./04-checkout-links.md).

---

## List

`GET /v1/stores`

| Query | Notes |
|-------|-------|
| `limit` | Page size. Defaults to 10, capped at 100. |
| `starting_after` | Opaque cursor from the previous page. |
| `active` | Optional. Omit it to list both active and inactive. |

```bash
curl "https://api.worthypayments.com/v1/stores?limit=10" \
  -H "x-api-key: sk_test_xxx"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "store_9x2",
      "object": "store",
      "slug": "acme-shop",
      "name": "Acme Shop",
      "description": "Everything Acme",
      "active": true,
      "show_prices": true,
      "product_count": 12
    }
  ],
  "has_more": false
}
```

---

## Stats

`GET /v1/stores/stats`. One roll-up across every storefront: counts and `total_revenue` in
cents.

```bash
curl https://api.worthypayments.com/v1/stores/stats \
  -H "x-api-key: sk_test_xxx"
```

```json
{
  "object": "store_stats",
  "total_stores": 3,
  "active_stores": 2,
  "inactive_stores": 1,
  "total_products": 47,
  "total_orders": 0,
  "total_revenue": 0
}
```

---

## Retrieve

`GET /v1/stores/{id}`. The same object as a list row. Unknown id is `404
resource_missing`.

---

## What is not here

There is no public `POST` / `PATCH` / `DELETE` for storefronts. Create and edit them in
the dashboard. `store.*` webhooks are not delivered on this API. They record
administrative catalogue edits, not shopper events. See [Webhooks](./16-webhooks.md).