직접 만들 필요 없는 커머스 백엔드

상품, 장바구니, 체크아웃, 주문, 고객, 재고 — 하나의 REST API로 모두 해결. 스토어프론트에만 집중하세요. 커머스는 저희가 처리합니다.

Headless Commerce SDK 데모 — 설치부터 주문까지 60초

MCP 서버

AI 에이전트(Claude, Cursor, ChatGPT)를 연결하여 자연어로 스토어를 관리하세요.

API 레퍼런스

Storefront와 Admin API의 100개 이상의 엔드포인트를 살펴보세요.

바이브 코딩 — 이 프롬프트를 AI 에이전트에 복사하세요

AI 에이전트 마스터 프롬프트 — 클릭하여 펼치기 & 복사

당신은 Headless Commerce API를 사용하여 이커머스 애플리케이션을 개발하는 개발자입니다.

## API 개요
- Base URL: https://api.headlesscommerce.io/v1
- 인증: Authorization: Bearer {API_KEY}
- Storefront API (pk_* 키): 고객용 — 상품, 장바구니, 체크아웃, 주문
- Admin API (sk_* 키): 서버 전용 — 상품 관리, 주문, 재고, 웹훅
- 키 유형: pk_test_* (개발 프론트엔드), pk_live_* (운영 프론트엔드), sk_test_* (개발 백엔드), sk_live_* (운영 백엔드)
- sk_* 키를 클라이언트 코드에 절대 노출하지 마세요

## SDK 설치
npm install @headless-commerce/sdk    # TypeScript
pip install headless-commerce          # Python

## SDK 초기화
// TypeScript — Storefront (클라이언트 안전)
import { createStorefrontClient } from '@headless-commerce/sdk';
const client = createStorefrontClient({ apiKey: 'pk_test_...' });

// TypeScript — Admin (서버 전용)
import { createAdminClient } from '@headless-commerce/sdk';
const admin = createAdminClient({ apiKey: 'sk_test_...' });

# Python
from headless_commerce import HeadlessCommerce
client = HeadlessCommerce(api_key="pk_test_...")
admin = HeadlessCommerce(api_key="sk_test_...")

## 핵심 흐름: 상품 → 장바구니 → 체크아웃
1. 상품 목록:       const { data } = await client.products.list({ limit: 20 })
2. 장바구니 생성:   const cart = await client.carts.create({ session_id: 'guest-123' })
3. 상품 추가:       await client.carts.addItem(cart.id, { variant_id: 'var_xxx', quantity: 1 })
4. 체크아웃:        const order = await client.carts.checkout(cart.id, {
                      email: 'customer@example.com',
                      shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
                      payment_method: 'stripe'  // 또는 'tosspayments', 'manual'
                    })

## 결제 연동
- Stripe: payment_method: 'stripe' → client_secret 반환 → 클라이언트에서 Stripe.js로 확인
- TossPayments: payment_method: 'tosspayments' → toss_payment 반환 → TossPayments Widget SDK로 확인

## 웹훅
- 생성: POST /admin/webhooks { url, events: ['order.confirmed', 'payment.completed'] }
- 검증: X-Webhook-Signature 헤더의 HMAC-SHA256 서명
- 이벤트: order.created, order.confirmed, order.completed, order.cancelled, payment.completed, payment.failed, payment.refunded, product.created, product.updated, product.deleted, fulfillment.created, fulfillment.shipped, fulfillment.delivered, inventory.low, inventory.out_of_stock, customer.created

## 고객 인증
- 서버에서 JWT 생성: POST /admin/customers/{id}/token → { token, expires_at }
- 클라이언트 전달: X-Customer-Token: {jwt} + Authorization: Bearer pk_*
- 비회원 장바구니: session_id로 생성, 로그인 후 POST /carts/{id}/merge로 병합

## 주요 패턴
- 페이지네이션: 커서 기반, limit (1-100, 기본값 20) 및 starting_after 사용
- 에러: JSON { error: { type, code, message, details } } + 표준 HTTP 상태 코드
- 멱등성: 체크아웃/결제/환불 POST에 Idempotency-Key 헤더 (UUID), 24시간 캐시

## MCP 서버 (AI 에이전트 직접 연결)
URL: https://mcp.headlesscommerce.io/mcp
헤더: Authorization: Bearer sk_live_your_key
지원: 상품, 주문, 고객, 재고, 할인, 풀필먼트, 장바구니, 웹훅, 리전, 배송, 반품, 환불, 스토어 설정, 대시보드 통계

## 전체 API 문서: https://docs.headlesscommerce.io
## API 레퍼런스: https://docs.headlesscommerce.io/api-reference/introduction

이 컨텍스트를 활용하여 사용자가 요청하는 것을 구현하세요. 깔끔하고 프로덕션에 바로 사용할 수 있는 코드를 작성하세요.

플랫폼 한눈에 보기

100+

Storefront & Admin API 엔드포인트

0%

거래 수수료 — 매출을 온전히 가져가세요

<50ms

글로벌 API 응답 시간 중앙값

99.9%

유료 플랜 업타임 SLA

60초 만에 개발 시작

API 키 발급

대시보드에 로그인하세요
설정 > API 키로 이동하세요
API 키 생성을 클릭하세요

키 접두사	유형	용도
`pk_test_*`	Publishable / Test	개발용 프론트엔드 (브라우저에 노출해도 안전)
`pk_live_*`	Publishable / Live	운영용 프론트엔드
`sk_test_*`	Secret / Test	개발용 백엔드 / 관리자
`sk_live_*`	Secret / Live	운영용 백엔드 / 관리자

시크릿 키(sk_*)를 클라이언트 코드에 절대 노출하지 마세요. 브라우저 및 모바일 애플리케이션에는 퍼블리셔블 키를 사용하세요.

SDK 설치

TypeScript / Node.js
Python

npm install @headless-commerce/sdk

pnpm add @headless-commerce/sdk

yarn add @headless-commerce/sdk

pip install headless-commerce

poetry add headless-commerce

uv add headless-commerce

클라이언트 초기화

환경 변수를 설정하세요:

.env

# Storefront (클라이언트 안전)
NEXT_PUBLIC_HC_API_KEY=pk_test_...

# Admin (서버 전용)
HC_SECRET_KEY=sk_test_...

TypeScript / Node.js
Python

import { createStorefrontClient } from '@headless-commerce/sdk';

const client = createStorefrontClient({
  apiKey: process.env.NEXT_PUBLIC_HC_API_KEY!,
  // 기본적으로 https://api.headlesscommerce.io/v1 에 연결됩니다
});

관리자 작업에는 서버 측에서 시크릿 키를 사용하세요:

import { createAdminClient } from '@headless-commerce/sdk';

const admin = createAdminClient({
  apiKey: process.env.HC_SECRET_KEY!,
});

from headless_commerce import HeadlessCommerce

# Storefront 클라이언트
client = HeadlessCommerce(api_key="pk_test_...")

# Admin 클라이언트
admin = HeadlessCommerce(api_key="sk_test_...")

또는 컨텍스트 매니저를 사용하여 자동으로 정리할 수 있습니다:

with HeadlessCommerce(api_key="sk_test_...") as admin:
    products = admin.products.list()

첫 쇼핑 플로우 구축

상품 목록 조회

const { data: products } = await client.products.list({ limit: 10 });
console.log(products);

products = client.products.list(limit=10)
print(products)

curl https://api.headlesscommerce.io/v1/storefront/products \
  -H "Authorization: Bearer pk_test_your_key_here"

응답 예시

{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Classic T-Shirt",
      "status": "active",
      "type": "physical",
      "variants": [
        { "id": "var_xxx", "name": "M / Black", "price": 2900 }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

장바구니 생성

const cart = await client.carts.create({
  session_id: 'guest-session-123',
});

console.log(cart.id); // cart_xxxxxxxx

cart = client.carts.create(session_id="guest-session-123")
print(cart["id"])  # cart_xxxxxxxx

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "guest-session-123"}'

상품 추가

await client.carts.addItem(cart.id, {
  variant_id: products[0].variants[0].id,
  quantity: 1,
});

client.carts.add_item(cart["id"], variant_id=products[0]["variants"][0]["id"], quantity=1)

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/items \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "var_xxx", "quantity": 1}'

체크아웃

const order = await client.carts.checkout(cart.id, {
  email: 'customer@example.com',
  shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
  payment_method: 'stripe',
});

// order.payment.client_secret을 Stripe.js와 함께 사용하여 결제를 완료하세요
console.log(order.payment.client_secret);

const order = await client.carts.checkout(cart.id, {
  email: 'customer@example.com',
  shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
  payment_method: 'tosspayments',
});

// order.toss_payment를 TossPayments SDK와 함께 사용하여 결제 UI를 표시하세요
const { order_id, order_name, amount } = order.toss_payment;

// 사용자가 TossPayments UI에서 결제를 완료한 후, 서버 측에서 확인하세요:
await client.payments.confirm({
  payment_key: paymentKey, // TossPayments SDK 콜백에서 받은 값
  order_id,
  amount,
});

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/checkout \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "payment_provider": "stripe",
    "payment_method_id": "pm_xxx"
  }'

이게 전부입니다 — 상품 탐색부터 주문 완료까지 네 단계면 충분합니다.

개발자를 위해 설계됨

두 개의 API, 하나의 플랫폼

고객용 앱을 위한 Storefront API (Publishable Key). 백오피스 관리를 위한 Admin API (Secret Key). 동일한 Base URL, 다른 권한 범위.

타입 안전 SDK

완전한 자동완성을 지원하는 TypeScript SDK. @headless-commerce/sdk를 설치하고 타입 안전하게 바로 개발을 시작하세요.

웹훅 & 이벤트

주문 생성, 결제 완료, 재고 변동 등 실시간 이벤트를 구독하세요. 폴링 없이 반응형 워크플로우를 구축할 수 있습니다.

대시보드 포함

상품, 주문, 고객, 재고를 관리할 수 있는 완전한 관리자 대시보드가 포함되어 있습니다 — 별도 설정 불필요.

MCP 서버

Claude 같은 AI 어시스턴트에 스토어를 연결하세요. 자연어로 상품, 주문, 재고를 관리할 수 있습니다.

결제 바로 연동

Stripe와 토스페이먼츠 내장 지원. 플랫폼 수수료 없이 글로벌 결제를 받으세요.

제공 기능

도메인	Storefront API	Admin API
상품 & 옵션	조회	전체 CRUD
카테고리 & 컬렉션	조회	전체 CRUD
장바구니 & 체크아웃	전체	—
주문 & 반품	본인 조회	전체 관리
고객 & 주소	셀프서비스	전체 CRUD
재고	—	전체 관리
할인	장바구니 적용	전체 CRUD
웹훅	—	전체 CRUD
결제 (Stripe, Toss)	확인	완료 처리
리전 & 다국어	조회	전체 CRUD
CSV 가져오기/내보내기	—	전체

어떤 프레임워크든 OK

이미 사용 중인 도구로 스토어프론트를 구축하세요. Headless Commerce는 순수 API — 프론트엔드에 대한 제약이 없습니다.

Next.js

React Server Components, App Router, SSR/SSG — 모두 지원됩니다.

Remix

Loaders, actions, 중첩 라우트 — 어디서든 Headless Commerce를 호출하세요.

Nuxt

SDK를 통한 완전한 TypeScript 지원으로 Vue 3 컴포저블을 사용하세요.

Svelte 외

Svelte, Astro, 모바일 앱, 또는 순수 REST — HTTP만 되면 연동됩니다.

다음 단계

MCP 서버

AI 에이전트를 연결하여 자연어로 스토어를 관리하세요.

SDK

TypeScript 및 Python SDK 레퍼런스 — 모든 리소스와 메서드를 확인하세요.

고객 인증

JWT 토큰, 비회원 장바구니, 고객 신원 확인.

API 레퍼런스

Storefront와 Admin API의 100개 이상의 REST 엔드포인트를 살펴보세요.

무료로 시작하기

신용카드 불필요. 테스트 모드에서 전체 API 접근 가능.

요금제 보기

심플하고 예측 가능한 요금. 거래 수수료 0%.

시작하기

AI와 함께 빌드

API 규칙

보안

결제 연동

레시피

소개

직접 만들 필요 없는 커머스 백엔드

MCP 서버

API 레퍼런스

바이브 코딩 — 이 프롬프트를 AI 에이전트에 복사하세요

플랫폼 한눈에 보기

100+

0%

<50ms

99.9%

60초 만에 개발 시작

개발자를 위해 설계됨

두 개의 API, 하나의 플랫폼

타입 안전 SDK

웹훅 & 이벤트

대시보드 포함

MCP 서버

결제 바로 연동

제공 기능

어떤 프레임워크든 OK

Next.js

Remix

Nuxt

Svelte 외

다음 단계

MCP 서버

SDK

고객 인증

API 레퍼런스

무료로 시작하기

요금제 보기

​직접 만들 필요 없는 커머스 백엔드

MCP 서버

API 레퍼런스

​바이브 코딩 — 이 프롬프트를 AI 에이전트에 복사하세요

​플랫폼 한눈에 보기

100+

0%

<50ms

99.9%

​60초 만에 개발 시작

​개발자를 위해 설계됨

두 개의 API, 하나의 플랫폼

타입 안전 SDK

웹훅 & 이벤트

대시보드 포함

MCP 서버

결제 바로 연동

​제공 기능

​어떤 프레임워크든 OK

Next.js

Remix

Nuxt

Svelte 외

​다음 단계

MCP 서버

SDK

고객 인증

API 레퍼런스

무료로 시작하기

요금제 보기

직접 만들 필요 없는 커머스 백엔드

바이브 코딩 — 이 프롬프트를 AI 에이전트에 복사하세요

플랫폼 한눈에 보기

60초 만에 개발 시작

개발자를 위해 설계됨

제공 기능

어떤 프레임워크든 OK

다음 단계