Merchant API reference
The REST API your server uses to read your Swop store and create checkouts.
Base URL
https://apps.apiswop.co/api/v5/merchantAll requests use HTTPS and JSON. Every request needs a merchant API key; see Authentication.
Endpoints
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /me | any | Check a key and see what it can do right now |
GET | /products | commerce.read | List your products |
GET | /orders | commerce.read | List your sales |
POST | /checkout-intents | commerce.checkout | Create a checkout from a cart |
GET | /checkout-intents/{intentId} | commerce.read | Read a checkout and its status |
POST | /embed-token | commerce.embed | Mint a token to frame checkout on a registered site |
GET | /locations | drops.read | List your physical locations |
GET | /locations/{id} | drops.read | Read one location |
GET | /locations/{id}/terminals | drops.read | List tap-to-pay terminals at a location |
Some things can only be done in the Swop app while signed in, never with an API key: creating and revoking keys, registering websites for framed checkout, and managing webhooks. That way a leaked key can never widen its own access.
Conventions
- Amounts are numbers in USDC (for example
29.85), not cents. - IDs: products and locations use 24-character hex IDs; checkouts use
co_…; keys usemk_…. - Timestamps are ISO 8601 in UTC.
- Success responses wrap the result in
data. Errors havesuccess: falseand amessage; see Errors.
Not available yet
| Status | |
|---|---|
| Test mode / sandbox keys | Coming soon. Every request is live. |
| Idempotency keys | Coming soon. A retried POST /checkout-intents creates a second checkout. |
| Refunds by API | Coming soon. Use the Swop app. |
| Creating or editing products by API | The commerce.write scope exists, but no product write endpoints are exposed on this API yet. |
| OpenAPI spec | Coming soon |