# SKU.io API Documentation

> SKU.io is a multitenant inventory-management platform (ERP) for multichannel
> ecommerce brands: sales orders, purchasing, inventory, products, accounting,
> and integrations with Amazon, Shopify, TikTok Shop, Walmart, WooCommerce,
> BigCommerce, eBay, Temu, QuickBooks Online, Xero, and 3PL/shipping providers.
> The API is REST + JSON. Base URL: https://{tenant}.sku.io — replace {tenant}
> with the account's subdomain. Authentication: Personal Access Token as a
> Bearer token on every request.

## Instructions for AI agents

- Authenticate every request with `Authorization: Bearer <token>`. Tokens are
  created in the SKU.io app under Settings → Developer → Personal Access Tokens.
- Tokens are scoped (orders:read, products:write, inventory:write, …) and
  deny-by-default: a 403 "not available to API tokens" means the token lacks a
  scope for that endpoint — a human must edit the token's scopes.
- Platform rate limit is 1,000 requests/min; per-token limits may be lower.
  On 429, honor the Retry-After header.
- The canonical machine-readable surface is the OpenAPI spec:
  https://developer.sku.io/openapi.yaml (~3,200 operations). Prefer the
  per-domain chunks over the full 6 MB file: fetch
  https://developer.sku.io/openapi/index.json for the catalog, then the
  chunk you need (e.g. /openapi/sales-orders.yaml, /openapi/amazon.yaml).
- Every docs page has a markdown twin: append `.md` to its URL
  (e.g. /docs/guides/quickstart.md) — far cheaper to read than the HTML.
- Paths under `/api/` are the primary integration surface. Paths under
  `/api/v2/` are a smaller read-mostly BFF layer — they are NOT version 2 of
  `/api/` and most resources have no `/api/v2/` write equivalent.
- Operations flagged `deprecated: true` in the spec must not be used in new
  integrations.
- List endpoints paginate with `page` / `per_page` (default 10) and return the
  Laravel envelope (`data`, `current_page`, `last_page`, `total`). Filter with
  `filter[field]=value`, sort with `sort=-created_at`.
- Destructive operations (DELETE, bulk-delete, cancel, void) are irreversible
  on live tenant data — confirm with a human before calling them.
- Webhook receiver endpoints (paths starting `/webhooks/` or matching
  `/api/webhooks/*/{token}`) are for platform callbacks, not for client use.

## Documentation

- [API Reference (by domain)](https://developer.sku.io/docs/api/introduction): full per-endpoint reference generated from the OpenAPI spec
- [Quickstart](https://developer.sku.io/docs/guides/quickstart): first authenticated call in five minutes
- [Authentication](https://developer.sku.io/docs/guides/authentication): Personal Access Tokens, header format, 401 handling
- [Pagination](https://developer.sku.io/docs/guides/pagination): page/per_page parameters and response envelope
- [Filtering & Sorting](https://developer.sku.io/docs/guides/filtering-and-sorting): filter[...] and sort query syntax
- [Errors](https://developer.sku.io/docs/guides/errors): response shapes for 401/403/404/422/500
- [Dates & Timezones](https://developer.sku.io/docs/guides/dates-and-timezones): UTC datetimes, app-timezone dates
- [Rate Limits](https://developer.sku.io/docs/guides/rate-limits): current limits and retry guidance
- [Webhooks](https://developer.sku.io/docs/guides/webhooks): subscriptions, event catalog, signature verification
- [API Conventions](https://developer.sku.io/docs/guides/api-conventions): /api vs /api/v2, URL structure, envelopes

## Machine-readable

- [OpenAPI 3.0 spec (YAML)](https://developer.sku.io/openapi.yaml): the entire API surface; operations are tagged by domain
- [Per-domain spec chunks](https://developer.sku.io/openapi/index.json): catalog of one-YAML-per-domain subsets — fetch a domain instead of the full spec
- [Postman collection (v2.1)](https://developer.sku.io/skuio-api.postman_collection.json): the full API as an importable Postman collection, generated from the same spec; set the `baseUrl` and `token` variables to run requests
- [Error catalog (JSON)](https://developer.sku.io/errors.json): every error status with body shapes, stable codes, and retry guidance
- [Webhook event catalog (JSON)](https://developer.sku.io/webhooks/events.json): all events with payload envelope, signing, and delivery semantics
- [Agent Skills manifest (JSON)](https://developer.sku.io/.well-known/skills.json): task-oriented skill files — find the right endpoint, create & fulfill an order, sync inventory, manage products, subscribe to webhooks
- [Agent operating manual](https://developer.sku.io/agents.md)
- [MCP server](https://www.npmjs.com/package/@skuio/docs-mcp): `npx -y @skuio/docs-mcp` — search_docs / fetch_doc / get_openapi tools over these docs
- [Sitemap](https://developer.sku.io/sitemap.xml)

## Updates

- [API Changelog](https://developer.sku.io/changelog): additions, changes, deprecations, and removals
- [Release Notes](https://developer.sku.io/release-notes): product-level feature announcements