Billing Subscriptions

Create Subscription

구독 생성 + 첫 결제 PG 제출.

post/v1/subscriptions

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

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

Idempotency-Keystring required
Authorizationstring 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 입니다.

Request body

organization_idinteger required

구독 소유 조직 PK. 주체 조직과 일치 강제.

plan_idinteger required

plans.id (ACTIVE 상태만 허용).

payment_method_idinteger required

payment_methods.id (ACTIVE 상태 + 본인 조직 소유만 허용).

metadataobject nullable

운영 메타데이터 (예: source, utm_*, referrer). PII/secret 적재 금지. 키 화이트리스트는 별도 결정.

addon_product_idsinteger[] nullable

Optional purchasable add-on api_products.id list. Must match ACTIVE plan_addon_offers for plan_id + env_scope.

Response

Successful Response

subscription_idinteger required

subscriptions.id.

organization_idinteger required

소유 조직 PK.

plan_idinteger required

plans.id.

payment_method_idinteger nullable

NULL = 결제창 인증 경로.

status'PENDING' | 'ACTIVE' | 'PAUSED' | 'CANCELED' | 'EXPIRED' | 'PAYMENT_FAILED' required

구독 상태. 본 응답은 보통 PENDING(202 Accepted).

env_scope'sandbox' | 'real_test' | 'production' required

환경 스코프.

first_invoice_idinteger required

구독 생성과 함께 발행된 첫 인보이스 ID(invoices.id, OPEN 상태).

first_payment_idinteger required

구독 생성과 함께 시도된 첫 결제 ID(payments.id, INITIATED/PENDING 상태).

created_atstring date-time required

구독 생성 시각 (aware datetime, naive 입력 시 422).

Changes

No recorded changes to this operation across all 1 revision of this API.