Back
Pickly
Architecture →
API v1 · Production

Pickly API Reference

REST · JSON · HTTPS only · Bearer authentication · ISO 8601 timestamps.

base_url:https://api.pickly.app/v1
Authentication
OAuth 2.0 bearer tokens. Refresh via /auth/refresh.
Rate limits
1,000 req/min per token. 429 with Retry-After header.
Errors
RFC 7807 problem+json. Stable error codes.
POST/v1/auth/token

Exchange credentials for a bearer token.

Request
{
  "email": "ava@pickly.app",
  "password": "••••••••"
}
Response · 200
{
  "access_token": "pk_live_...",
  "refresh_token": "pkr_...",
  "expires_in": 3600,
  "user": { "id": "u_cust_1", "role": "customer" }
}

Webhooks

Subscribe via POST /v1/webhooks. Payloads signed with HMAC-SHA256 (header Pickly-Signature). Auto-retries with exponential backoff for non-2xx, up to 24h.

order.createdFired when a new order is placed.
order.readyFired when merchant marks order ready.
payment.capturedFired when a payment is captured.
payment.refundedFired on full/partial refund.
inventory.low_stockFired when product available < threshold.

Error format

{
  "type": "https://docs.pickly.app/errors/inventory_unavailable",
  "title": "Not enough stock",
  "status": 409,
  "detail": "Only 2 Almond Croissants available.",
  "code": "inventory_unavailable",
  "request_id": "req_01HNTX..."
}