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

# Manage your store via API

> Catalog, orders, customers, and configuration with the Admin API.

The **Admin API** (`/api/v1/admin/*`) exposes complete store management: catalog,
pricing, stock, orders, customers, content, marketing, reports, settings. It's designed for
backends, integrations (ERP/PIM/billing), and automations — including
[AI agents via MCP](/en/ai-mcp).

## Authentication & permissions

You need a **staff token** with the appropriate permissions:

```
Authorization: Bearer <staff_access_token>
```

Permissions are granular: `catalog`, `sales`, `customers`, `content`, `marketing`,
`reports`, `tax`, `users`, `system`. A token can read/write only in the areas allowed by its
role, and every call is scoped to **its own store** (the `tenant_id` claim).

<Warning>
  The Admin API is **server-side**. Never embed a staff token in a public client.
</Warning>

## Examples

```bash theme={null}
# list products (includes inactive ones, for management)
curl "$BASE/api/v1/admin/products?page=1&page_size=24" -H "Authorization: Bearer $STAFF"

# create a product
curl -X POST "$BASE/api/v1/admin/products" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "name":"...", "slug":"...", ... }'

# orders + status change (with validated transitions)
curl "$BASE/api/v1/admin/orders?status=pending" -H "Authorization: Bearer $STAFF"
curl -X PATCH "$BASE/api/v1/admin/orders/<id>" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "status":"processing" }'
```

## Best practices

* **Idempotency & bulk**: for mass updates (prices, stock), process in batches and
  handle 409/422 responses per row.
* **Audit**: every admin mutation is recorded in the store's audit log.
* **Soft-delete**: deleting a product/category sets `deleted_at` (it doesn't destroy the
  order history); deactivating is a different thing (`is_active`).
* **Versioning**: the API lives under `/api/v1` — backward-compatible changes; breaking
  changes will go into a new version.

The full reference for the \~200 admin endpoints is in the
[API Reference](/en/api-reference) (the `admin` sections), generated from the live OpenAPI schema.