Overview

End-to-end recipes for the common integrations.

Nine end-to-end recipes, each written against endpoints that exist today. Every field name is the real one, and every sample runs.

The guides

Guide	What it covers	You need
Create an order	Resolving a customer and variants, placing the order idempotently, and reading what comes back.	`orders:write`, `products:read`
Sync inventory to an ERP	The `updated_after` + cursor pattern, checkpoints that survive a crash, and why offset paging is not offered.	`products:read`, `inventory:read`
Handle webhooks idempotently	Verify, de-duplicate, upsert, answer fast — the whole receiver.	A webhook endpoint
Build a custom storefront	Reading the catalogue, checking availability, taking an order and recording payment.	Read scopes, `orders:write`, `payments:write`
Build a COD confirmation tool	The call queue, finding an order by any phone form, customer history, and recording the outcome.	`orders:write`, `customers:read`
Sales and reports	The sales summary, comparisons and top products, and the basis of each figure.	`reports:read`
Build a catalog through the API	An attribute, a category and a brand, then a product with variants, options and photos — in four calls.	`products:write`, `catalog:write`
Photos by link	Where image links are taken, what is checked, all-or-nothing calls, the limits and safe retries.	`products:write` or `catalog:write`
Upload a product video	An upload with raw calls from start to finish, a cover, a video shown for one option, imports by link, reject codes and limits.	`videos:write`, `products:read`

Before any of them

Create a key with only the scopes that guide needs (Authentication). Start with a store key.
Export it as SHOPDESK_API_KEY — every sample in these docs reads it from the environment rather than inlining it.
Point at /ext/v1 — https://api.shopdeskbd.com/ext/v1. There is no shorter /v1 alias.

export SHOPDESK_API_KEY="shopdesk_sk_YOUR_API_KEY"
 
curl -sS "https://api.shopdeskbd.com/ext/v1/products?limit=1" \
  -H "Authorization: Bearer $SHOPDESK_API_KEY"

If that returns a product, you are ready for any of them.

Every integration in this list ends up leaning on the same four things, so they are worth learning once:

Cursor pagination — limit + starting_after + meta.has_more.
Incremental sync — updated_after with a watermark.
Idempotent writes — one key per logical operation.
One error shape — branch on code, log the request_id.

The guides

Before any of them

The patterns they share