IAP.getProductItemList

인앱결제로 구매할 수 있는 상품 목록을 가져옵니다. 상품 목록 화면에 진입할 때 호출하며, 소모품·비소모품·구독 세 가지 타입을 포함한 IapProductListItem 배열을 반환합니다.

시그니처

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

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

declare const IAP: {
  getProductItemList(): Promise<{
    products: IapProductListItem[];
  }>;
  // ...overview 참고
};

파라미터

없음.

반환값

Promise<{ products: IapProductListItem[] }> — 상품 목록 객체.

IapProductListItem은 ConsumableProductListItem | NonConsumableProductListItem | SubscriptionProductListItem 유니언 타입입니다.

공통 필드 (BasicProductListItem)

필드	타입	설명
sku	string	상품 고유 ID.
displayName	string	화면에 표시할 상품 이름.
displayAmount	string	통화 단위 포함 가격 문자열 (예: 1,000원).
iconUrl	string	상품 아이콘 URL.
description	string	상품 설명.

타입별 추가 필드

타입	추가 필드
CONSUMABLE	type: 'CONSUMABLE'
NON_CONSUMABLE	type: 'NON_CONSUMABLE'
SUBSCRIPTION	type: 'SUBSCRIPTION', renewalCycle: 'WEEKLY' | 'MONTHLY' | 'YEARLY', offers?: Offer[]

앱 버전이 최소 지원 버전(Android 5.219.0 / iOS 5.219.0)보다 낮으면 undefined를 반환할 수 있습니다.

권한

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

예제

최소 예제

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

const result = await IAP.getProductItemList();
const products = result?.products ?? [];
console.log(products);

실전 예제 — 타입별 렌더링

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

function ProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  useEffect(() => {
    IAP.getProductItemList().then((result) => {
      setProducts(result?.products ?? []);
    });
  }, []);

  return (
    <ul>
      {products.map((product) => (
        <li key={product.sku}>
          <span>{product.displayName}</span>
          <span>{product.displayAmount}</span>
          {product.type === 'SUBSCRIPTION' && (
            <span>갱신 주기: {product.renewalCycle}</span>
          )}
        </li>
      ))}
    </ul>
  );
}

직접 실행해 보기

sdk-example의 IAP 페이지에서 getProductItemList를 실행해 상품 목록을 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• IAP.createOneTimePurchaseOrder — 상품 조회 후 단건 구매로 이동합니다.
• IAP.createSubscriptionPurchaseOrder — 구독 상품 구매로 이동합니다.
• IAP.getCompletedOrRefundedOrders — 구매 완료·환불 내역을 조회합니다.

관련 가이드

• Guides — IAP 상태 조회 패턴 — 상품 목록·미처리 주문·환불 동기화·구독 상태를 진입 시 한 번에 관리하는 패턴.

외부 참조

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