# 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](https://www.shopdeskbd.com/developers/guide-create-an-order.md)                 | Resolving a customer and variants, placing the order idempotently, and reading what comes back.                                 | `orders:write`, `products:read`               |
| [Sync inventory to an ERP](https://www.shopdeskbd.com/developers/guide-sync-inventory.md)         | The `updated_after` + cursor pattern, checkpoints that survive a crash, and why offset paging is not offered.                   | `products:read`, `inventory:read`             |
| [Handle webhooks idempotently](https://www.shopdeskbd.com/developers/guide-handle-webhooks.md)    | Verify, de-duplicate, upsert, answer fast — the whole receiver.                                                                 | A webhook endpoint                            |
| [Build a custom storefront](https://www.shopdeskbd.com/developers/guide-custom-storefront.md)     | Reading the catalogue, checking availability, taking an order and recording payment.                                            | Read scopes, `orders:write`, `payments:write` |
| [Build a COD confirmation tool](https://www.shopdeskbd.com/developers/guide-cod-confirmation.md)  | The call queue, finding an order by any phone form, customer history, and recording the outcome.                                | `orders:write`, `customers:read`              |
| [Sales and reports](https://www.shopdeskbd.com/developers/guide-sales-reports.md)                 | The sales summary, comparisons and top products, and the basis of each figure.                                                  | `reports:read`                                |
| [Build a catalog through the API](https://www.shopdeskbd.com/developers/guide-build-a-catalog.md) | 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](https://www.shopdeskbd.com/developers/guide-photos-by-link.md)                   | 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](https://www.shopdeskbd.com/developers/guide-upload-a-product-video.md)   | 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

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

```bash
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.

## The patterns they share

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`](https://www.shopdeskbd.com/developers/pagination.md#walking-every-page).
- **Incremental sync** — [`updated_after` with a watermark](https://www.shopdeskbd.com/developers/pagination.md#syncing-changes-with-updated_after).
- **Idempotent writes** — [one key per logical operation](https://www.shopdeskbd.com/developers/idempotency.md#idempotency-key).
- **One error shape** — [branch on `code`, log the `request_id`](https://www.shopdeskbd.com/developers/errors.md#handling-errors-well).