IAP.getSubscriptionInfo

특정 주문 ID로 구독의 현재 상태를 조회합니다. 구독 유효 여부(isAccessible), 만료 일시, 자동 갱신 설정 등을 확인할 수 있습니다.

시그니처

getSubscriptionInfo는 IAP 네임스페이스 객체의 멤버로 노출됩니다.

import { IAP } from '@apps-in-toss/web-framework';

declare const IAP: {
  getSubscriptionInfo(args: {
    params: { orderId: string };
  }): Promise<{
    subscription: {
      catalogId: number;
      status: string;
      expiresAt: string | null;
      isAutoRenew: boolean;
      gracePeriodExpiresAt: string | null;
      isAccessible: boolean;
    };
  }>;
  // ...overview 참고
};

파라미터

이름	타입	필수	설명
args.params.orderId	string	✓	상태를 조회할 구독 주문의 고유 ID.

반환값

Promise<IapSubscriptionInfoResponse> — 구독 상태 정보.

필드	타입	설명
subscription.catalogId	number	구독 카탈로그 ID.
subscription.status	string	구독 상태 문자열.
subscription.expiresAt	string | null	구독 만료 일시 (ISO 8601). 만료 정보가 없으면 null.
subscription.isAutoRenew	boolean	자동 갱신 여부.
subscription.gracePeriodExpiresAt	string | null	유예 기간 만료 일시. 유예 기간이 없으면 null.
subscription.isAccessible	boolean	구독 콘텐츠 접근 가능 여부.

권한

권한이 필요하지 않습니다 — IAP 네임스페이스는 별도의 PermissionName에 바인딩되지 않습니다.

예제

최소 예제

import { IAP } from '@apps-in-toss/web-framework';

const result = await IAP.getSubscriptionInfo({ params: { orderId: 'order-123' } });
console.log(result.subscription);

실전 예제 — 구독 상태에 따른 콘텐츠 게이팅

import { IAP } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

interface Props {
  orderId: string;
}

function SubscriptionGate({ orderId }: Props) {
  const [accessible, setAccessible] = useState(false);

  useEffect(() => {
    IAP.getSubscriptionInfo({ params: { orderId } }).then((result) => {
      setAccessible(result.subscription.isAccessible);
    });
  }, [orderId]);

  if (!accessible) {
    return <p>구독이 필요한 콘텐츠입니다.</p>;
  }

  return <p>구독 콘텐츠 표시</p>;
}

직접 실행해 보기

sdk-example의 IAP 페이지 "주문 관리" 단계에서 이 API를 실행해 볼 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• IAP.createSubscriptionPurchaseOrder — 구독 구매 주문서로 이동합니다.
• IAP.getCompletedOrRefundedOrders — 구독을 포함한 완료·환불 주문 목록을 조회합니다.
• IAP.getPendingOrders — 대기 중인 주문을 조회합니다.

관련 가이드

• Guides — IAP 상태 조회 패턴 — getSubscriptionInfo로 구독성 화면 게이트와 갱신/환불 반영.

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.