## Base URL

All API requests are made to your store's domain:

```
https://your-store.yns.store/api/v1/
```

## Authentication

Every request requires a Bearer token in the `Authorization` header. API keys are managed in your store's admin settings under **Settings → API → API keys**.

```bash
curl https://your-store.yns.store/api/v1/products \
  -H "Authorization: Bearer your_api_key"
```

Each API key is scoped to a single store. All data returned is isolated to that store. Keys can also be scoped to specific capabilities – see [API Key Scopes](/docs/commerce-sdk/authentication#api-key-scopes) for the full list.

## Request Format

- **Content-Type**: `application/json` for POST, PATCH, and PUT requests
- **Query parameters** for filtering and pagination on GET requests
- Path parameters use UUID v7 identifiers or URL slugs (e.g. `/products/classic-tee`)

## Response Format

All responses return JSON. Successful list responses use this shape:

```json
{
  "data": [
    { "id": "019...", "name": "Classic Tee", "slug": "classic-tee" }
  ],
  "meta": {
    "count": 42
  }
}
```

Single resource responses return the object directly:

```json
{
  "id": "019...",
  "name": "Classic Tee",
  "slug": "classic-tee"
}
```

## Pagination

List endpoints support offset-based pagination:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 10-50 | Max items to return (1-100) |
| `offset` | `number` | 0 | Items to skip |

Some endpoints (inventory) use cursor-based pagination with a `cursor` parameter instead.

## Error Responses

Errors return an appropriate HTTP status code with a JSON body:

```json
{
  "error": "Invalid request data",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "message": "Product name is required",
      "path": ["name"]
    }
  ]
}
```

| Status | Meaning |
|--------|---------|
| `400` | Validation error – invalid parameters or request body |
| `401` | Unauthorized – missing or invalid API key |
| `403` | Forbidden – API key is missing the required scope for this endpoint |
| `404` | Not found – resource doesn't exist |
| `409` | Conflict – slug or unique constraint violation |
| `500` | Server error |

## OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

```
GET /api/v1/openapi
```

This spec is auto-generated from the actual Zod schemas used in route handlers, so it's always in sync with the API.

## MCP Server

Every store is also reachable over the [Model Context Protocol](https://modelcontextprotocol.io) at `https://yns.store/mcp`, so an agent can run store operations without you building an integration first. Authentication, the two tools it exposes and a ready-to-paste client config are on the [MCP Server](/docs/api-reference/mcp-server) page.

## Public Content API

Distinct from everything above: the marketing site publishes its own **keyless** API for the documentation, help centre, pricing and changelog, plus three storefront-analysis endpoints. No key, no sign-up, every operation a `GET`.

| URL | What it is |
|-----|------------|
| [`/openapi.json`](https://yournextstore.com/openapi.json) | OpenAPI 3.1 description of that API |
| [`/.well-known/api-catalog`](https://yournextstore.com/.well-known/api-catalog) | RFC 9727 catalog listing both this Store API and the content API |
| [`/llms.txt`](https://yournextstore.com/llms.txt) | Index of every docs page and help article, with summaries |

Any documentation page or help article also has a markdown representation at its normal URL – send `Accept: text/markdown`, or append `.md`:

```bash
curl -H "Accept: text/markdown" https://yournextstore.com/docs/api-reference/products
curl https://yournextstore.com/docs/api-reference/products.md
```

| Operation | Endpoint |
|-----------|----------|
| `getSiteOverviewMarkdown` | `GET /api/index-md` |
| `getDocumentationPage` | `GET /api/docs/{section}/{slug}` |
| `getHelpArticle` | `GET /api/help/{category}/{slug}` |
| `getPricing` / `getPricingMarkdown` | `GET /api/pricing`, `GET /api/pricing-md` |
| `getLatestChangelog` | `GET /api/changelog/latest` |
| `scanStore` | `GET /api/store-scan?url=` – platform, plugin cost, security and AI-visibility report (10 req/min per IP) |
| `getPageSpeedReport` | `GET /api/pagespeed?url=` – mobile and desktop Lighthouse results (5 req/min per IP) |
| `getPageMetadata` | `GET /api/fetch-page-meta?url=` – title, description and OG image (20 req/min per IP) |

### Content API errors

Unlike the Store API above, the content API answers every non-2xx with [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem details, served as `application/problem+json`:

```json
{
  "type": "https://yournextstore.com/docs/api-reference/overview#content-api-errors",
  "title": "Document not found",
  "status": 404,
  "detail": "The requested documentation page does not exist.",
  "instance": "https://yournextstore.com/api/docs/api-reference/nope",
  "code": "document_not_found",
  "resolution": "List every document available in markdown at https://yournextstore.com/llms.txt.",
  "documentationUrl": "https://yournextstore.com/docs/api-reference/overview#content-api-errors"
}
```

Branch on `code`, never on `title` – `title` is prose and may be reworded.

Each `type` below is the anchor of the matching subsection, so a caller can follow it straight to the explanation.

#### API route not found

`404`, `code: api_route_not_found`. No endpoint is served at that path. Discover the real surface through `/openapi.json` or `/.well-known/api-catalog`.

#### Document not found

`404`, `code: document_not_found`. The section, category or slug names no page that exists. Every valid pair is listed in `/llms.txt` and enumerated in `/openapi.json`.

#### Missing parameter

`400`, `code: missing_parameter`. A required query parameter was absent – in practice always `url`.

#### Invalid parameter

`400`, `code: invalid_parameter`. A parameter was present but unusable, e.g. a `url` that is neither an absolute http(s) URL nor a hostname.

#### Rate limited

`429`, `code: rate_limited`. The per-IP window for that endpoint is exhausted. Wait for `Retry-After` seconds and retry.

#### Upstream unavailable

`502`, `code: upstream_unavailable`. A third party the endpoint depends on – the storefront being scanned, or the PageSpeed API – did not answer usefully. Retrying rarely helps until the upstream recovers.

## Available Endpoints

| Resource | Endpoints |
|----------|-----------|
| [Store](/docs/api-reference/store) | Read the store profile, theme, enabled modules, languages, and currencies |
| [Localization](/docs/api-reference/localization) | Serve translated content and per-currency prices |
| [Products](/docs/api-reference/products) | List, create, get, update, delete, batch, CSV import, variants, reviews, filters, reset catalog |
| [Variants](/docs/api-reference/variants) | Get, update, and delete product variants |
| [Bundles](/docs/api-reference/bundles) | List, create, get, update, and delete product bundles |
| [Collections](/docs/api-reference/collections) | List, create, get, update, delete, and CSV membership import |
| [Categories](/docs/api-reference/categories) | List, create, get, update, and delete, with nesting |
| [Brands](/docs/api-reference/brands) | List, create, get, update, delete, and assign products |
| [Inventory](/docs/api-reference/inventory) | List stock levels and adjust inventory |
| [Search](/docs/api-reference/search) | Full-text product search |
| [Reviews](/docs/api-reference/reviews) | Moderate reviews, plus list and create per product |
| [Orders](/docs/api-reference/orders) | List, get, update, shipments, labels, and refunds |
| [Carts](/docs/api-reference/carts) | Create, get, delete, line items, coupons, and checkout redirect |
| [Customers](/docs/api-reference/customers) | List, get, update, addresses, and customer orders |
| [Coupons](/docs/api-reference/coupons) | List, create, get, update, and delete discount codes |
| [Promotions](/docs/api-reference/promotions) | List, create, get, update, and delete automatic promotions |
| [Subscription Plans](/docs/api-reference/subscription-plans) | Recurring plans products can attach to |
| [Loyalty](/docs/api-reference/loyalty) | Settings, tiers, and campaigns |
| [Shipping](/docs/api-reference/shipping) | List, create, get, update, and delete shipping methods |
| [Addons](/docs/api-reference/addons) | Connected services, carrier connections, and InstaView images |
| [Tax Rates](/docs/api-reference/tax-rates) | List, create, get, update, and delete manual tax rates |
| [Pickup Locations](/docs/api-reference/pickup-locations) | Collection points offered at checkout |
| [Events](/docs/api-reference/events) | List, create, get, update, attendees, check-in roster, and networking directory |
| [Tickets](/docs/api-reference/tickets) | Buyer ticket lookup, attendee profiles, and door check-in |
| [Posts](/docs/api-reference/posts) | Blog post CRUD and per-post comments |
| [Blog Categories](/docs/api-reference/blog-categories) | List, create, get, update, and delete blog categories |
| [Post Comments](/docs/api-reference/post-comments) | Moderate, approve, reject, and delete comments |
| [Subscribers](/docs/api-reference/subscribers) | List, create, import, and delete newsletter subscribers |
| [Availability Notifications](/docs/api-reference/availability-notifications) | Register a back-in-stock alert request |
| [Newsletters](/docs/api-reference/newsletters) | Draft, send, and retry newsletter campaigns |
| [Contact Messages](/docs/api-reference/contact-messages) | Storefront messages: list, read, reply, and delete |
| [Media](/docs/api-reference/media) | Upload files, ingest remote URLs, and manage the media library |
| [Imports](/docs/api-reference/imports) | Start and track catalog import jobs |
| [Images](/docs/api-reference/images) | AI image generation and generation history |
| [Brand Kit](/docs/api-reference/brand-kit) | Get, update, and delete the store's brand kit |
| [Socials](/docs/api-reference/socials) | Get and set social profile links |
| [Analytics](/docs/api-reference/analytics) | Overview metrics and sales reporting |
| [Settings](/docs/api-reference/settings) | Store settings and checkout consents |
| [Team](/docs/api-reference/team) | Members, invitations, and ownership transfer |
| [Domain](/docs/api-reference/domain) | Connect, verify, and remove a custom domain |
| [Legal Pages](/docs/api-reference/legal-pages) | List, create, get, and update legal documents |
| [Support Cases](/docs/api-reference/support-cases) | Open, track, update, and reply to support cases |
| [Feedback Sessions](/docs/api-reference/feedback-sessions) | Start, comment on, cancel, and finalize feedback sessions |
| [Publish](/docs/api-reference/publish) | Trigger a storefront publish and poll its status |