API 레퍼런스
Headless Commerce API는 REST 기반으로 설계되었습니다. JSON 요청 본문을 받고, JSON 응답을 반환하며, 표준 HTTP 메서드와 상태 코드를 사용합니다.Base URL
두 가지 API
Storefront API
/v1/storefront/*고객 대면 애플리케이션용. Publishable Key(pk_*) 또는 Secret Key(sk_*)로 접근 가능합니다.Admin API
/v1/admin/*백오피스 관리용. Secret Key(sk_*)만 필요합니다.공통 헤더
| 헤더 | 필수 | 설명 |
|---|---|---|
Authorization | 예 | Bearer <api_key> |
Content-Type | POST/PATCH 시 | application/json |
X-Customer-Token | 조건부 | 인증된 Storefront 엔드포인트용 고객 JWT |
Idempotency-Key | 권장 | 중요 POST 요청의 고유 키 |
Rate Limiting
요청은 플랜에 따라 스토어별로 제한됩니다:| 플랜 | 제한 |
|---|---|
| Free | 100 req/min |
| Starter | 500 req/min |
| Pro | 2,000 req/min |
| Enterprise | 커스텀 |
| 헤더 | 설명 |
|---|---|
X-RateLimit-Limit | 분당 최대 요청 수 |
X-RateLimit-Remaining | 현재 윈도우의 잔여 요청 수 |
X-RateLimit-Reset | 윈도우 리셋 Unix 타임스탬프 |