---
title: "Get Plan"
method: GET
path: "/v1/plans/{plan_id}"
tags: ["Billing Plans"]
---

# Get Plan

`GET /v1/plans/{plan_id}`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/plans/{plan_id}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

요금제 상세 조회.

## Path parameters

- `plan_id` integer, required

## Query parameters

- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Response `200`

Successful Response

- PlanResponse: 요금제 단일 객체 응답. SCHEMA → DTO 매핑: - `plans.id` → `plan_id` (외부 노출 식별자명 — 표준 `<resource>_id` 패턴). - `plans.code/name/description/tier/billing_cycle/status/env_scope/created_at` → 직접 매핑. - `plans.price_amount_minor + currency + tax_included` → nested `MoneyMinor` 객체 `price`. - `plans.metadata`/`updated_at`/`deleted_at`는 외부 노출 X(BFF/콘솔 미사용 + 정책 평가 키 보호). SCHEMA가 글로벌 카탈로그이므로 `organization_id` 필드 없음.
  - `plan_id` integer, required: plans.id (BIGSERIAL PK).
  - `code` string, required: 비즈 식별 코드. 환경 내 유니크 (SCHEMA uq_plans_code_env_active).
  - `name` string, required: 사용자 노출 명칭.
  - `description` string, nullable: 요금제 설명 (마크다운 허용).
  - `tier` 'FREE' | 'PAID', required: 요금제 등급. FREE/PAID.
  - `billing_cycle` 'ONCE' | 'MONTHLY' | 'YEARLY', required: 청구 주기. ONCE/MONTHLY/YEARLY.
  - `price` MoneyMinor, required: minor unit 정수 기반 금액 객체. SCHEMA 컬럼 `price_amount_minor BIGINT NOT NULL CHECK (>= 0)` + `currency CHAR(3) DEFAULT 'KRW'` + `tax_included BOOLEAN DEFAULT TRUE`를 API 응답의 nested `price` 객체로 묶는다. - `amount_minor`: 1회 청구/결제 금액의 minor unit 정수(KRW는 원 단위, JPY는 엔 단위). 절대 float/Decimal 사용 금지(부동소수 오차 + JSON 직렬화 일관성). - `currency`: v1 단일 KRW. 통화 확장은 별도 ADR. - `tax_included`: 부가세 포함 여부. NULL 금지(SCHEMA NOT NULL DEFAULT TRUE 정합).
    - `amount_minor` integer, required: minor unit 정수 금액. KRW는 원 단위. 음수 금지 (SCHEMA CHECK 정합).
    - `currency` 'KRW', required: 통화 코드 (v1=KRW). 세 글자여야 한다.
    - `tax_included` boolean, required: 부가세 포함 여부. SCHEMA NOT NULL.
  - `status` 'DRAFT' | 'ACTIVE' | 'DEPRECATED' | 'RETIRED', required: 요금제 상태.
  - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
  - `created_at` string, date-time, required: 발행 시각 (TIMESTAMPTZ, ISO 8601 + offset 포함; naive 입력 시 422).
  - `addon_select_min` integer, nullable: W6/G7: min Path B pack count at subscribe (NULL=unlimited).
  - `addon_select_max` integer, nullable: W6/G7: max Path B pack count (NULL=unlimited).
  - `audience` 'standard' | 'integrator': 기본값 standard · 연동사 요금제는 integrator.
  - `max_active_account_links` integer, nullable: 연동사 요금제의 좌석 상한 - 한 desktop_agent 클라이언트가 가질 수 있는 ACTIVE account_links 최대 수. audience='integrator' 일 때만 뜻이 있고 NULL 은 제한 없음(또는 해당 없음)이다.
  - `included_usage_free_units` integer, nullable: 요금제 전체의 종량 무료 허용량(한 청구 기간 기준) - (sum of all data_provider/action usage_records quantity, not per action). NULL or 0 = no free allowance (billed from unit 1, current behavior).
  - `daily_token_limit` integer, nullable: T12: daily usage-token allowance this plan grants, read from the linked quota_policies row (plans.quota_policy_id). The unit is usage tokens, not call count. null means THIS PLAN HAS NO DAILY CAP from a quota policy - do not read it as not-configured-yet. It covers four cases that are deliberately not distinguished: no policy linked, a linked policy whose own daily_limit is null, a linked policy that was soft-deleted, and the admin create/update responses (those are built from RETURNING, which this repository keeps narrow - read the plan again to get the limits).
  - `monthly_token_limit` integer, nullable: T12: monthly usage-token allowance from the same quota_policies row. NULL = no monthly limit for this plan (the user instruction gives a monthly number for the paid plans only). The unit is usage tokens.
  - `contact_sales` boolean: 상담으로 가입하는 요금제(엔터프라이즈)이면 true. 고객이 스스로 가입하는 길(0원 가입 · 결제 가입)에 서지 않는다. 입력값을 받지 않고 `code` 에서 유도한다(`CONTACT_SALES_PLAN_CODES`).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)