# Shopdesk Commerce API The public API for merchants and their integrations. Authenticate with `Authorization: Bearer shopdesk_sk_…`. Keys are issued from the dashboard under Settings → Developer, and their secret is shown exactly once. Conventions: fields are snake_case; timestamps are ISO-8601 in UTC; monetary amounts are strings with two decimals ("1250.00") so decimal precision survives JSON. Lists are cursor-paginated — pass the previous page's `meta.next_cursor` as `starting_after`. Every operation declares the scope it needs as `x-required-scope`. A key holding `:write` also satisfies `:read`. The one operation any valid key may call, `GET /me`, is marked `x-any-api-key` instead. ## Introduction - [Getting started](https://www.shopdeskbd.com/developers/getting-started.md): From no key to your first response, in five minutes. - [Authentication](https://www.shopdeskbd.com/developers/authentication.md): Key format, store vs company keys, rotation, revocation. - [Build with AI](https://www.shopdeskbd.com/developers/ai.md): Markdown twins, llms.txt, the spec URL, and the two MCP servers. ## Core concepts - [Errors](https://www.shopdeskbd.com/developers/errors.md): The error envelope, every code, and what to do with each. - [Pagination](https://www.shopdeskbd.com/developers/pagination.md): Cursor paging, the sync pattern, and why sorting is limited. - [Writes & idempotency](https://www.shopdeskbd.com/developers/idempotency.md): Every write endpoint, and the Idempotency-Key contract behind them. - [Rate limits](https://www.shopdeskbd.com/developers/rate-limits.md): Per-key buckets, headers, and handling 429. - [Versioning](https://www.shopdeskbd.com/developers/versioning.md): What we may change without warning, and what we may not. ## API reference - [Overview](https://www.shopdeskbd.com/developers/reference.md): Generated from the published OpenAPI description. - [Products](https://www.shopdeskbd.com/developers/reference/products.md): 11 Products endpoints (GET, POST, PATCH, DELETE), generated from the OpenAPI description. - [Categories](https://www.shopdeskbd.com/developers/reference/categories.md): 4 Categories endpoints (GET, POST, PATCH), generated from the OpenAPI description. - [Brands](https://www.shopdeskbd.com/developers/reference/brands.md): 4 Brands endpoints (GET, POST, PATCH), generated from the OpenAPI description. - [Attributes](https://www.shopdeskbd.com/developers/reference/attributes.md): 6 Attributes endpoints (GET, POST, PATCH), generated from the OpenAPI description. - [Orders](https://www.shopdeskbd.com/developers/reference/orders.md): 8 Orders endpoints (GET, POST, PATCH), generated from the OpenAPI description. - [Customers](https://www.shopdeskbd.com/developers/reference/customers.md): 4 Customers endpoints (GET, POST, PATCH), generated from the OpenAPI description. - [Inventory](https://www.shopdeskbd.com/developers/reference/inventory.md): 3 Inventory endpoints (POST, GET), generated from the OpenAPI description. - [Locations](https://www.shopdeskbd.com/developers/reference/locations.md): 2 Locations endpoints (GET), generated from the OpenAPI description. - [Channels](https://www.shopdeskbd.com/developers/reference/channels.md): 1 Channels endpoint (GET), generated from the OpenAPI description. - [Store](https://www.shopdeskbd.com/developers/reference/store.md): 2 Store endpoints (GET), generated from the OpenAPI description. - [Reports](https://www.shopdeskbd.com/developers/reference/reports.md): 2 Reports endpoints (GET), generated from the OpenAPI description. - [Videos](https://www.shopdeskbd.com/developers/reference/videos.md): 10 Videos endpoints (POST, DELETE, GET), generated from the OpenAPI description. - [MCP tools](https://www.shopdeskbd.com/developers/mcp-tools.md): Every store MCP tool — scopes, arguments, metering, output — generated from the tool manifest. ## Webhooks - [Overview](https://www.shopdeskbd.com/developers/webhooks.md): Outbound events: the envelope, the guarantees, the rules. - [Event catalog](https://www.shopdeskbd.com/developers/webhook-events.md): Every event type we send, and what each one carries. - [Verifying signatures](https://www.shopdeskbd.com/developers/webhook-signatures.md): The signing scheme, code in three languages, and test vectors. - [Retries & ordering](https://www.shopdeskbd.com/developers/webhook-retries.md): The retry ladder, dead deliveries, and auto-disable. - [Testing](https://www.shopdeskbd.com/developers/webhook-testing.md): The shopdesk.ping event and how to develop against it. - [Headers](https://www.shopdeskbd.com/developers/webhook-headers.md): Every header on a delivery, and what to do with it. - [Rotating a secret](https://www.shopdeskbd.com/developers/webhook-rotation.md): The dual-signing window, and what a receiver does during it. ## Guides - [Overview](https://www.shopdeskbd.com/developers/guides.md): End-to-end recipes for the common integrations. - [Create an order](https://www.shopdeskbd.com/developers/guide-create-an-order.md): Customer, variants, idempotency key, and what comes back. - [Sync inventory to an ERP](https://www.shopdeskbd.com/developers/guide-sync-inventory.md): Cursors, watermarks and checkpoints that survive a crash. - [Handle webhooks idempotently](https://www.shopdeskbd.com/developers/guide-handle-webhooks.md): Verify, dedupe, upsert, and answer fast. - [Build a custom storefront](https://www.shopdeskbd.com/developers/guide-custom-storefront.md): The read path, checkout, and what the API does not give you. - [Build a COD confirmation tool](https://www.shopdeskbd.com/developers/guide-cod-confirmation.md): Find the order by phone, confirm or cancel it, schedule the call-back. - [Sales and reports](https://www.shopdeskbd.com/developers/guide-sales-reports.md): The sales summary, comparisons and top products, and what each figure counts. - [Build a catalog through the API](https://www.shopdeskbd.com/developers/guide-build-a-catalog.md): Attributes, a category and a brand, then a product with variants and photos — in four calls. - [Photos by link](https://www.shopdeskbd.com/developers/guide-photos-by-link.md): Where links are taken, what is checked, all-or-nothing calls, limits and safe retries. - [Upload a product video](https://www.shopdeskbd.com/developers/guide-upload-a-product-video.md): Raw calls from start to finish, covers, a video for one option, imports by link, reject codes and limits. ## Reference material - [Changelog](https://www.shopdeskbd.com/developers/changelog.md): Every change to the public API, newest first. ## Machine-readable - [OpenAPI 3.0 description](https://www.shopdeskbd.com/openapi/public-v1.json): every endpoint, parameter, schema and scope — the artifact this documentation is generated from. - [llms.txt](https://www.shopdeskbd.com/llms.txt): this documentation as an index for AI tools. - [llms-full.txt](https://www.shopdeskbd.com/llms-full.txt): every page in one markdown document.