# Shopdesk Commerce API — reference

Version `2026-08`, generated from the [published OpenAPI description](https://www.shopdeskbd.com/openapi/public-v1.json). 57 endpoints — 25 reads and 32 writes.

Paths are shown exactly as the server routes them — prefix them with `https://api.shopdeskbd.com`. Authenticate with two headers, no handshake:

```http
Authorization: Bearer shopdesk_sk_YOUR_API_KEY
Accept: application/json
```

A key with `<resource>:write` also satisfies `<resource>:read`; the reverse is never true. Writes take an `Idempotency-Key` — see [Writes & idempotency](https://www.shopdeskbd.com/developers/idempotency.md).

## Resources

- **[Products](https://www.shopdeskbd.com/developers/reference/products.md)** — 11 endpoints
  - `GET /ext/v1/products` — [List products](https://www.shopdeskbd.com/developers/reference/products.md#list-products) · scope `products:read`
  - `POST /ext/v1/products` — [Create a product](https://www.shopdeskbd.com/developers/reference/products.md#create-a-product) · scope `products:write`
  - `GET /ext/v1/products/{id}` — [Get a product by id](https://www.shopdeskbd.com/developers/reference/products.md#get-a-product-by-id) · scope `products:read`
  - `PATCH /ext/v1/products/{id}` — [Update a product](https://www.shopdeskbd.com/developers/reference/products.md#update-a-product) · scope `products:write`
  - `POST /ext/v1/products/{id}/archive` — [Archive a product](https://www.shopdeskbd.com/developers/reference/products.md#archive-a-product) · scope `products:write`
  - `POST /ext/v1/products/{id}/images` — [Add product images](https://www.shopdeskbd.com/developers/reference/products.md#add-product-images) · scope `products:write`
  - `PATCH /ext/v1/products/{id}/images/{imageId}` — [Update a product image](https://www.shopdeskbd.com/developers/reference/products.md#update-a-product-image) · scope `products:write`
  - `DELETE /ext/v1/products/{id}/images/{imageId}` — [Delete a product image](https://www.shopdeskbd.com/developers/reference/products.md#delete-a-product-image) · scope `products:write`
  - `POST /ext/v1/products/{id}/images/reorder` — [Reorder product images](https://www.shopdeskbd.com/developers/reference/products.md#reorder-product-images) · scope `products:write`
  - `GET /ext/v1/variants/{identifier}` — [Get a variant by id, SKU or barcode](https://www.shopdeskbd.com/developers/reference/products.md#get-a-variant-by-id-sku-or-barcode) · scope `products:read`
  - `PATCH /ext/v1/variants/{identifier}` — [Update a variant](https://www.shopdeskbd.com/developers/reference/products.md#update-a-variant) · scope `products:write`
- **[Categories](https://www.shopdeskbd.com/developers/reference/categories.md)** — 4 endpoints
  - `GET /ext/v1/categories` — [List categories](https://www.shopdeskbd.com/developers/reference/categories.md#list-categories) · scope `products:read`
  - `POST /ext/v1/categories` — [Create a category](https://www.shopdeskbd.com/developers/reference/categories.md#create-a-category) · scope `catalog:write`
  - `GET /ext/v1/categories/{id}` — [Get a category by id](https://www.shopdeskbd.com/developers/reference/categories.md#get-a-category-by-id) · scope `products:read`
  - `PATCH /ext/v1/categories/{id}` — [Update a category](https://www.shopdeskbd.com/developers/reference/categories.md#update-a-category) · scope `catalog:write`
- **[Brands](https://www.shopdeskbd.com/developers/reference/brands.md)** — 4 endpoints
  - `GET /ext/v1/brands` — [List brands](https://www.shopdeskbd.com/developers/reference/brands.md#list-brands) · scope `products:read`
  - `POST /ext/v1/brands` — [Create a brand](https://www.shopdeskbd.com/developers/reference/brands.md#create-a-brand) · scope `catalog:write`
  - `GET /ext/v1/brands/{id}` — [Get a brand by id](https://www.shopdeskbd.com/developers/reference/brands.md#get-a-brand-by-id) · scope `products:read`
  - `PATCH /ext/v1/brands/{id}` — [Update a brand](https://www.shopdeskbd.com/developers/reference/brands.md#update-a-brand) · scope `catalog:write`
- **[Attributes](https://www.shopdeskbd.com/developers/reference/attributes.md)** — 6 endpoints
  - `GET /ext/v1/attributes` — [List attributes](https://www.shopdeskbd.com/developers/reference/attributes.md#list-attributes) · scope `products:read`
  - `POST /ext/v1/attributes` — [Create an attribute](https://www.shopdeskbd.com/developers/reference/attributes.md#create-an-attribute) · scope `catalog:write`
  - `GET /ext/v1/attributes/{id}` — [Get an attribute by id](https://www.shopdeskbd.com/developers/reference/attributes.md#get-an-attribute-by-id) · scope `products:read`
  - `PATCH /ext/v1/attributes/{id}` — [Update an attribute](https://www.shopdeskbd.com/developers/reference/attributes.md#update-an-attribute) · scope `catalog:write`
  - `POST /ext/v1/attributes/{id}/values` — [Add a value to an attribute](https://www.shopdeskbd.com/developers/reference/attributes.md#add-a-value-to-an-attribute) · scope `catalog:write`
  - `PATCH /ext/v1/attributes/{id}/values/{valueId}` — [Update an attribute value](https://www.shopdeskbd.com/developers/reference/attributes.md#update-an-attribute-value) · scope `catalog:write`
- **[Orders](https://www.shopdeskbd.com/developers/reference/orders.md)** — 8 endpoints
  - `GET /ext/v1/orders` — [List orders](https://www.shopdeskbd.com/developers/reference/orders.md#list-orders) · scope `orders:read`
  - `POST /ext/v1/orders` — [Create an order](https://www.shopdeskbd.com/developers/reference/orders.md#create-an-order) · scope `orders:write`
  - `GET /ext/v1/orders/{id}` — [Get an order by id](https://www.shopdeskbd.com/developers/reference/orders.md#get-an-order-by-id) · scope `orders:read`
  - `PATCH /ext/v1/orders/{id}` — [Update an order's note and follow-up](https://www.shopdeskbd.com/developers/reference/orders.md#update-an-orders-note-and-follow-up) · scope `orders:write`
  - `POST /ext/v1/orders/{id}/cancel` — [Cancel an order](https://www.shopdeskbd.com/developers/reference/orders.md#cancel-an-order) · scope `orders:write`
  - `GET /ext/v1/orders/{id}/payments` — [List an order's payments](https://www.shopdeskbd.com/developers/reference/orders.md#list-an-orders-payments) · scope `payments:read`
  - `POST /ext/v1/orders/{id}/payments` — [Record a payment against an order](https://www.shopdeskbd.com/developers/reference/orders.md#record-a-payment-against-an-order) · scope `payments:write`
  - `PATCH /ext/v1/orders/{id}/status` — [Change an order status](https://www.shopdeskbd.com/developers/reference/orders.md#change-an-order-status) · scope `orders:write`
- **[Customers](https://www.shopdeskbd.com/developers/reference/customers.md)** — 4 endpoints
  - `GET /ext/v1/customers` — [List customers](https://www.shopdeskbd.com/developers/reference/customers.md#list-customers) · scope `customers:read`
  - `POST /ext/v1/customers` — [Create a customer](https://www.shopdeskbd.com/developers/reference/customers.md#create-a-customer) · scope `customers:write`
  - `GET /ext/v1/customers/{id}` — [Get a customer by id, with their addresses](https://www.shopdeskbd.com/developers/reference/customers.md#get-a-customer-by-id-with-their-addresses) · scope `customers:read`
  - `PATCH /ext/v1/customers/{id}` — [Update a customer](https://www.shopdeskbd.com/developers/reference/customers.md#update-a-customer) · scope `customers:write`
- **[Inventory](https://www.shopdeskbd.com/developers/reference/inventory.md)** — 3 endpoints
  - `POST /ext/v1/inventory/adjustments` — [Adjust stock at a location](https://www.shopdeskbd.com/developers/reference/inventory.md#adjust-stock-at-a-location) · scope `inventory:write`
  - `GET /ext/v1/inventory/levels` — [List stock levels (one row per variant per location)](https://www.shopdeskbd.com/developers/reference/inventory.md#list-stock-levels-one-row-per-variant-per-location) · scope `inventory:read`
  - `GET /ext/v1/inventory/movements` — [List stock movements (the append-only ledger behind the levels)](https://www.shopdeskbd.com/developers/reference/inventory.md#list-stock-movements-the-append-only-ledger-behind-the-levels) · scope `inventory:read`
- **[Locations](https://www.shopdeskbd.com/developers/reference/locations.md)** — 2 endpoints
  - `GET /ext/v1/locations` — [List locations](https://www.shopdeskbd.com/developers/reference/locations.md#list-locations) · scope `locations:read`
  - `GET /ext/v1/locations/{id}` — [Get a location by id](https://www.shopdeskbd.com/developers/reference/locations.md#get-a-location-by-id) · scope `locations:read`
- **[Channels](https://www.shopdeskbd.com/developers/reference/channels.md)** — 1 endpoint
  - `GET /ext/v1/channels` — [List sales channels](https://www.shopdeskbd.com/developers/reference/channels.md#list-sales-channels) · scope `channels:read`
- **[Store](https://www.shopdeskbd.com/developers/reference/store.md)** — 2 endpoints
  - `GET /ext/v1/me` — [Describe the calling API key](https://www.shopdeskbd.com/developers/reference/store.md#describe-the-calling-api-key)
  - `GET /ext/v1/store` — [Get the store profile](https://www.shopdeskbd.com/developers/reference/store.md#get-the-store-profile) · scope `store:read`
- **[Reports](https://www.shopdeskbd.com/developers/reference/reports.md)** — 2 endpoints
  - `GET /ext/v1/reports/sales-summary` — [Get a sales summary for a window](https://www.shopdeskbd.com/developers/reference/reports.md#get-a-sales-summary-for-a-window) · scope `reports:read`
  - `GET /ext/v1/reports/top-products` — [List the top products for a window](https://www.shopdeskbd.com/developers/reference/reports.md#list-the-top-products-for-a-window) · scope `reports:read`
- **[Videos](https://www.shopdeskbd.com/developers/reference/videos.md)** — 10 endpoints
  - `POST /ext/v1/products/{id}/videos` — [Place a video on a product](https://www.shopdeskbd.com/developers/reference/videos.md#place-a-video-on-a-product) · scope `videos:write`
  - `DELETE /ext/v1/products/{id}/videos/{videoId}` — [Take a video off a product](https://www.shopdeskbd.com/developers/reference/videos.md#take-a-video-off-a-product) · scope `videos:write`
  - `GET /ext/v1/videos` — [List your video uploads](https://www.shopdeskbd.com/developers/reference/videos.md#list-your-video-uploads) · scope `videos:write`
  - `POST /ext/v1/videos` — [Start a video upload](https://www.shopdeskbd.com/developers/reference/videos.md#start-a-video-upload) · scope `videos:write`
  - `GET /ext/v1/videos/{id}` — [Get a video upload](https://www.shopdeskbd.com/developers/reference/videos.md#get-a-video-upload) · scope `videos:write`
  - `DELETE /ext/v1/videos/{id}` — [Delete a video upload](https://www.shopdeskbd.com/developers/reference/videos.md#delete-a-video-upload) · scope `videos:write`
  - `POST /ext/v1/videos/{id}/complete` — [Complete a video upload](https://www.shopdeskbd.com/developers/reference/videos.md#complete-a-video-upload) · scope `videos:write`
  - `POST /ext/v1/videos/{id}/part-urls` — [Get upload URLs for video parts](https://www.shopdeskbd.com/developers/reference/videos.md#get-upload-urls-for-video-parts) · scope `videos:write`
  - `POST /ext/v1/videos/{id}/poster` — [Set a video cover](https://www.shopdeskbd.com/developers/reference/videos.md#set-a-video-cover) · scope `videos:write`
  - `POST /ext/v1/videos/import` — [Import a video from a link](https://www.shopdeskbd.com/developers/reference/videos.md#import-a-video-from-a-link) · scope `videos:write`