Promotion.grantReward

함수형 API grantPromotionReward로도 같은 기능을 쓸 수 있어요. 함수형 API는 v2와 같은 { params: { promotionCode, amount } } 형태의 인자를 받고, 미지원 앱 버전이면 에러 대신 undefined를 반환해요.

기능 설명

프로모션 코드를 사용해 유저에게 리워드(토스 포인트)를 지급해요.

토스앱 5.232.0 이상에서 사용할 수 있어요. 호출 전에 Promotion.grantReward.isSupported()로 지원 여부를 확인할 수 있어요. 지원하지 않는 버전에서 호출하면 UNSUPPORTED_APP_VERSION 에러가 발생해요.

타입

Promotion.grantReward(params: { promotionCode: string; amount: number }): Promise<GrantPromotionRewardResponse>;

Params

{
  /** 프로모션 코드예요. */
  promotionCode: string;
  /** 지급할 포인트 금액이에요. */
  amount: number;
}

Response

type GrantPromotionRewardResponse = {
  /** 리워드 키예요. */
  key: string;
};

• { key: string }: 포인트 지급에 성공했어요. key는 리워드 키예요.

에러

포인트 지급에 실패하면 실패 코드를 담은 에러가 throw돼요. 에러 코드는 catch한 에러의 error.code 값이에요.

코드	설명
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. Promotion.grantReward.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.
4100	프로모션 정보를 찾을 수 없는 경우예요.
4104	프로모션이 중지된 경우예요.
4105	프로모션이 종료된 경우예요.
4108	프로모션이 승인되지 않은 경우예요.
4109	프로모션이 실행중이 아닌 경우예요.
4110	리워드를 지급/회수할 수 없는 경우예요.
4112	프로모션 머니가 부족한 경우예요.
4113	이미 지급/회수된 내역인 경우예요.
4114	프로모션에 설정된 1회 지급 금액을 초과한 경우예요.
UNKNOWN_ERROR	알 수 없는 오류가 발생한 경우예요.

함수형 API grantPromotionReward는 v2와 동일하게 reject되지 않고 실패를 { errorCode: string; message: string } 값 또는 'ERROR' 문자열로 반환해요.

예시 코드

import { Promotion } from "@apps-in-toss/web-framework";

async function handleGrantReward() {
  try {
    if (!Promotion.grantReward.isSupported()) {
      console.warn("지원하지 않는 앱 버전이에요.");
      return;
    }

    const result = await Promotion.grantReward({
      promotionCode: "PROMOTION_CODE",
      amount: 1000,
    });

    console.log("포인트 지급 성공!", result.key);
  } catch (error) {
    console.error("포인트 지급 실패:", error.code, error.message);
  }
}

document
  .querySelector("#grant-reward")
  .addEventListener("click", handleGrantReward);