# Salaf Commerce API

The public API for merchants and their integrations.

Authenticate with `Authorization: Bearer salaf_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 `<resource>:write` also satisfies `<resource>:read`.

## Introduction

- [Getting started](https://www.salafems.com/developers/getting-started.md): From no key to your first response, in five minutes.
- [Authentication](https://www.salafems.com/developers/authentication.md): Key format, store vs company keys, rotation, revocation.
- [Build with AI](https://www.salafems.com/developers/ai.md): Markdown twins, llms.txt, the spec URL, and the two MCP servers.

## Core concepts

- [Errors](https://www.salafems.com/developers/errors.md): The error envelope, every code, and what to do with each.
- [Pagination](https://www.salafems.com/developers/pagination.md): Cursor paging, the sync pattern, and why sorting is limited.
- [Writes & idempotency](https://www.salafems.com/developers/idempotency.md): Every write endpoint, and the Idempotency-Key contract behind them.
- [Rate limits](https://www.salafems.com/developers/rate-limits.md): Per-key buckets, headers, and handling 429.
- [Versioning](https://www.salafems.com/developers/versioning.md): What we may change without warning, and what we may not.

## API reference

- [Overview](https://www.salafems.com/developers/reference.md): Generated from the published OpenAPI description.
- [Products](https://www.salafems.com/developers/reference/products.md): 6 Products endpoints (GET, POST, PATCH), generated from the OpenAPI description.
- [Categories](https://www.salafems.com/developers/reference/categories.md): 2 Categories endpoints (GET), generated from the OpenAPI description.
- [Brands](https://www.salafems.com/developers/reference/brands.md): 2 Brands endpoints (GET), generated from the OpenAPI description.
- [Orders](https://www.salafems.com/developers/reference/orders.md): 7 Orders endpoints (GET, POST, PATCH), generated from the OpenAPI description.
- [Customers](https://www.salafems.com/developers/reference/customers.md): 4 Customers endpoints (GET, POST, PATCH), generated from the OpenAPI description.
- [Inventory](https://www.salafems.com/developers/reference/inventory.md): 3 Inventory endpoints (POST, GET), generated from the OpenAPI description.
- [Locations](https://www.salafems.com/developers/reference/locations.md): 2 Locations endpoints (GET), generated from the OpenAPI description.
- [Channels](https://www.salafems.com/developers/reference/channels.md): 1 Channels endpoint (GET), generated from the OpenAPI description.

## Webhooks

- [Overview](https://www.salafems.com/developers/webhooks.md): Outbound events: the envelope, the guarantees, the rules.
- [Event catalog](https://www.salafems.com/developers/webhook-events.md): Every event type we send, and what each one carries.
- [Verifying signatures](https://www.salafems.com/developers/webhook-signatures.md): The signing scheme, code in three languages, and test vectors.
- [Retries & ordering](https://www.salafems.com/developers/webhook-retries.md): The retry ladder, dead deliveries, and auto-disable.
- [Testing](https://www.salafems.com/developers/webhook-testing.md): The salaf.ping event and how to develop against it.
- [Headers](https://www.salafems.com/developers/webhook-headers.md): Every header on a delivery, and what to do with it.
- [Rotating a secret](https://www.salafems.com/developers/webhook-rotation.md): The dual-signing window, and what a receiver does during it.

## Guides

- [Overview](https://www.salafems.com/developers/guides.md): End-to-end recipes for the four common integrations.
- [Create an order](https://www.salafems.com/developers/guide-create-an-order.md): Customer, variants, idempotency key, and what comes back.
- [Sync inventory to an ERP](https://www.salafems.com/developers/guide-sync-inventory.md): Cursors, watermarks and checkpoints that survive a crash.
- [Handle webhooks idempotently](https://www.salafems.com/developers/guide-handle-webhooks.md): Verify, dedupe, upsert, and answer fast.
- [Build a custom storefront](https://www.salafems.com/developers/guide-custom-storefront.md): The read path, checkout, and what the API does not give you.

## Reference material

- [Changelog](https://www.salafems.com/developers/changelog.md): Every change to the public API, newest first.

## Machine-readable

- [OpenAPI 3.0 description](https://www.salafems.com/openapi/public-v1.json): every endpoint, parameter, schema and scope — the artifact this documentation is generated from.
- [llms.txt](https://www.salafems.com/llms.txt): this documentation as an index for AI tools.
- [llms-full.txt](https://www.salafems.com/llms-full.txt): every page in one markdown document.