요금제와 한도

요금제는 상점마다 하나입니다. 상위 요금제는 하위 요금제의 기능을 모두 포함합니다. 쇼핑몰 기능(상품·주문·배송·클레임·결제·고객·쿠폰· 리뷰·문의)은 모든 요금제에서 쓰고 판매 수수료는 0%입니다. 결제 수수료는 셀러가 계약한 PG 요율 그대로입니다.

상점 플랫폼에서 설정 › 요금제로 이동하면 현재 요금제와 이번 기간 사용량을 봅니다(소유자·관리자).

베타 기간

지금은 베타 기간이라 모든 상점이 베타 요금제를 무료로 씁니다. 베타 요금제의 한도는 프리미엄 요금제 기준입니다.

• 정식 요금제는 시작 60일 전에 메일과 상점 플랫폼으로 알려 드립니다. 알림 기간에도 무료입니다.
• 정식 요금제가 시작된 뒤 90일 안에 유료 요금제를 고른 베타 상점은 첫 12개월 요금을 30% 할인합니다.
• 자동으로 결제하지 않습니다. 결제수단을 등록하고 요금제를 고른 상점만 청구합니다. 고르지 않은 상점은 Free 요금제로 바뀌고 데이터와 주문은 그대로입니다.
• 베타 기간에도 사용량과 한도에 닿은 기록을 남깁니다. 관리 API·애널리틱스·MCP 한도는 정식 요금제가 시작될 때부터 적용합니다.

요금제

표시 가격은 부가세 포함 월 요금입니다. 결제는 월 단위로만 합니다. 요금제 값은 바뀔 수 있습니다. 지금 값은 요금제 비교표 API로 봅니다.

• 관리 API는 액세스 토큰과 외부 앱 토큰으로 부르는 /v1/**입니다. Free 요금제에서도 토큰은 만들 수 있지만 그 토큰으로 부르면 403 PLAN_FEATURE_REQUIRED입니다. 상점 플랫폼·로컬 개발 CLI·MCP는 모든 요금제에서 씁니다.
• 애널리틱스는 Pro부터입니다. 구매자 행동 수집은 요금제와 무관하게 계속하므로 요금제를 올리면 쌓인 데이터를 바로 봅니다.
• 스토어프론트 월 트래픽은 스토어프론트 API 요청 수입니다. 넘어도 막지 않고 상위 요금제를 안내합니다. 구매자 쪽 속도·오류는 요금제로 깎지 않습니다. 남용을 막는 요청 속도 상한만 사이트마다 두고, 상위 요금제일수록 높습니다.
• 라이브 주문 수와 sayren이 보내는 메일에는 한도가 없습니다. 라이브 주문 수는 사용량으로만 보입니다.
• 계정당 상점은 3개입니다(요금제와 무관, 폐쇄한 상점은 세지 않음). 더 필요하면 고객 지원에 요청합니다.
• 엔터프라이즈는 계약으로 가입합니다. 표의 「계약」 항목은 계약에서 정합니다.

요금제 비교표 API

GET /v1/public/plans는 인증 없이 공개 요금제의 지금 값을 줍니다. 5분 동안 캐시할 수 있습니다. 요금제 값은 바뀔 수 있으니 코드에 수치를 두지 말고 이 응답을 읽습니다.

const { vatPercent, plans } = await api.plans.listPublic();
plans.map((plan) => [plan.name, plan.prices.vatIncluded.monthly]);
// [["Free", 0], ["Pro", 22000], ["프리미엄", 66000], ["엔터프라이즈", 110000]]

요금제가 바뀔 때

요금제 값이 바뀌면 새 버전으로 게시합니다. 새 상점과 요금제를 바꾸는 상점은 새 버전을 쓰고, 이미 쓰고 있는 상점은 따로 옮길 때까지 지금 버전의 값을 그대로 씁니다. 가격을 올려 기존 상점을 옮길 때는 60일 전에 메일과 상점 플랫폼으로 알려 드립니다.

요금 결제

정식 요금제가 시작된 뒤의 결제 방식입니다. 베타 기간에는 결제하지 않습니다.

유료 요금제는 상점 플랫폼 설정 › 요금제에서 소유자가 고르고 결제합니다. 공개 API·SDK·에이전트로는 요금제를 바꾸거나 결제하지 않습니다.

• 요금은 매월 결제일에 등록한 카드로 한 달 치를 미리 결제합니다. 요금제를 올리면 바로 적용하고 남은 기간 차액을 결제합니다. 내리거나 해지하면 다음 결제일에 바뀌고 환불하지 않습니다.
• 결제에 실패하면 1일·3일·7일 뒤 다시 결제합니다. 14일 안에 결제되지 않으면 Free 요금제로 바뀝니다. 그 사이에도 주문 접수·결제·발송·환불은 그대로입니다.
• Free 요금제로 바뀌면 데이터는 지우지 않습니다. 한도를 넘는 항목은 새로 만들 수 없습니다.
• 상점을 만들 때 유료 요금제를 바로 고를 수 있습니다(선택). 고르면 첫 결제를 한 뒤에 쓰고, 첫 결제 전에는 관리 API가 402 STORE_PAYMENT_REQUIRED입니다. 24시간 안에 결제하지 않으면 상점을 닫습니다.

공정 사용 한도

요금에 포함된 원가 항목입니다. 한도를 넘으면 해당 작업만 멈추고 다음 기간에 초기화됩니다.

편집 환경 시간은 편집 환경을 시작한 때부터 닫힌 때까지입니다. 작업이 없으면 15분 뒤 닫히고, 연결이 끊긴 환경은 닫힘을 확인하기까지 최대 2시간이 더 셀 수 있습니다. 빌드 시간은 빌드 한 번에 최대 15분까지 셉니다.

관리 API는 남용을 막는 레이트 리밋이 있습니다. 상점 플랫폼·MCP 요청은 관리 API 요청으로 세지 않고 액세스 토큰·외부 앱 요청만 셉니다. 발주 확인·발송·배송 완료·판매자 취소·클레임 처리는 한도와 레이트 리밋에서 뺍니다.

MCP 읽기·쓰기

MCP(에이전트)의 요청은 관리 API 요청 대신 MCP 읽기·쓰기로 셉니다.

• 한도는 기간마다 초기화되고 남은 횟수는 이월하지 않습니다.
• 쓰기 한도를 다 쓰면 에이전트의 새 쓰기와 새 승인 요청이 429 PLAN_AI_ACTIONS_EXCEEDED입니다. 사람이 이미 승인한 작업은 실행합니다.
• 읽기 한도를 다 쓰면 에이전트의 읽기가 429 PLAN_AI_READS_EXCEEDED입니다. 쓰기 한도와 따로 셉니다.
• 발주 확인·발송·배송 완료·판매자 취소·클레임 처리는 쓰기 한도를 넘어도 막지 않습니다(셈은 합니다).
• 한도 판정은 1분 단위로 갱신합니다. 한도 직전에는 몇 건이 더 실행될 수 있습니다.

사용량 조회

GET /v1/store/subscription(스코프 store:r)이 현재 요금제, 사용량 기간, 한도, 이번 기간 사용량을 줍니다. 결제수단과 청구 금액은 싣지 않습니다. 요금제 변경은 상점 플랫폼에서만 합니다.

const subscription = await api.subscription.get();
subscription.plan; // { code: "BETA", name: "베타" }
subscription.aiActions; // { limit: 10000, used: 12, resetsAt: "2026-10-31T15:00:00.000Z" }
subscription.aiReads; // { limit: 100000, used: 340, resetsAt: "2026-10-31T15:00:00.000Z" }

한도 오류

한도에 닿은 오류는 모두 error.details에 같은 형식을 싣습니다. 기존 오류 코드(STORE_LIMIT_EXCEEDED·STOREFRONT_DOMAIN_LIMIT· WEBHOOK_LIMIT_EXCEEDED)는 그대로이고 details에 필드만 더했습니다.

store-sdk는 실패를 ApiError로 던집니다. planErrorDetailsSchema로 details를 읽습니다.

import { ApiError, planErrorDetailsSchema } from "@sayren/store-sdk";

try {
  await api.products.patch(productId, { name });
} catch (error) {
  if (error instanceof ApiError && error.code === "PLAN_FEATURE_REQUIRED") {
    const details = planErrorDetailsSchema.parse(error.details ?? {});
    // 관리 API는 Pro부터다 — 사용자에게 요금제 화면을 안내한다
    return notify(`관리 API는 Pro 요금제부터 씁니다. ${details.upgradeUrl ?? ""}`);
  }
  if (error instanceof ApiError && error.code === "PLAN_API_QUOTA_EXCEEDED") {
    // Retry-After만큼 기다린 뒤 한 번 다시 보낸다
  }
  throw error;
}