---
title: "Get Subscription"
method: GET
path: "/v1/subscriptions/{subscription_id}"
tags: ["Billing Subscriptions"]
---

# Get Subscription

`GET /v1/subscriptions/{subscription_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/subscriptions/{subscription_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

- `subscription_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

- SubscriptionResponse: 구독 단일 객체 응답. SCHEMA → DTO 매핑: - `subscriptions.id` → `subscription_id`. - `organization_id/payment_method_id/status/env_scope/current_period_*/next_billing_at/ grace_period_until/canceled_at/created_at` → 직접 매핑. - `plans.id` + `plans.code` + `plans.tier` → nested `PlanSummary` 객체 `plan` (BFF가 plan 별도 조회 회피). - ACTIVE `subscription_items` → `addon_items[]` (Service enrich; mapper default []). - `cancel_reason`/`metadata`/`updated_at`/`deleted_at`/`plan_id` 직접 노출 X (cancel_reason은 감사로그/운영 API에서 조회). `payment_method_id`는 SCHEMA `NULL 허용`(자동 결제 미설정 가능)이므로 Optional.
  - `subscription_id` integer, required: subscriptions.id.
  - `organization_id` integer, required: 소유 조직 PK.
  - `plan` PlanSummary, required: 요금제 요약 객체(nested 응답용). `GET /v1/subscriptions/{id}` 응답 등 다른 자원이 요금제를 nested로 표시할 때 사용한다. 전체 `PlanResponse`(가격·주기·메타 포함)보다 가벼운 요약으로 분리 (응답 크기 최소화 + BFF 캐시 효율). **`name` 은 2026-09-15 에 들어왔다**(결정 큐 D-2(나), 사용자 승인 2026-09-13). 그전에는 식별자/코드/등급 3필드였는데, 콘솔이 구독 제목을 그릴 값이 없어 `PAID_BASIC_V1` 같은 **코드를 고객에게 보여 주거나** 자기 쪽에 이름 표를 또 두어야 했다. 둘 다 정책 위반이라(고객 노출 문구는 DB 가 정본) 여기 한 칸을 늘렸다. `plans.name` 은 `VARCHAR(200) NOT NULL` 이므로 Optional 이 아니다 - 기본값을 두면 읽기 경로가 빠뜨렸을 때 제목이 조용히 비어 나간다(검수 원장 #56 과 같은 이유).
    - `plan_id` integer, required: plans.id.
    - `code` string, required: 비즈 식별 코드.
    - `tier` 'FREE' | 'PAID', required: 요금제 등급. FREE/PAID.
    - `name` string, required: 고객에게 보이는 요금제 이름(`plans.name`). 콘솔이 구독 제목에 그대로 쓴다 - 코드(`PAID_BASIC_V1`)를 고객에게 보여 줄 수는 없기 때문이다.
  - `payment_method_id` integer, nullable: 활성 결제수단 ID. SCHEMA NULL 허용 (수동 청구 모드 가능).
  - `status` 'PENDING' | 'ACTIVE' | 'PAUSED' | 'CANCELED' | 'EXPIRED' | 'PAYMENT_FAILED', required: 구독 상태 (6값 enum).
  - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
  - `current_period_start` string, date-time, nullable: 현재 청구 기간 시작 (PENDING 시 NULL 가능).
  - `current_period_end` string, date-time, nullable: 현재 청구 기간 종료 (PENDING 시 NULL 가능).
  - `next_billing_at` string, date-time, nullable: 다음 자동 청구 시각 (PAUSED/CANCELED/EXPIRED 시 NULL).
  - `grace_period_until` string, date-time, nullable: 결제 실패 유예 종료 시각 (PAYMENT_FAILED 상태에서 채워짐).
  - `canceled_at` string, date-time, nullable: 취소 시각 (CANCELED 진입 시 채워짐).
  - `created_at` string, date-time, required: 구독 생성 시각 (aware datetime, naive 입력 시 422).
  - `addon_items` SubscriptionAddonItemResponse[]: ACTIVE Path B packs (product_name for Console subscription card).
    - `product_id` integer, required: api_products.id.
    - `product_name` string, required: api_products.name.
    - `amount_minor` integer, required: subscription_items.amount_minor snapshot (renewal line).
    - `currency` 'KRW', required: 통화 코드. v1=KRW.

## 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)