grantPromotionReward

프로모션 코드를 사용해 사용자에게 포인트 리워드를 지급합니다. 모든 카테고리의 미니앱에서 호출할 수 있습니다. 게임 카테고리 전용이었던 grantPromotionRewardForGame의 후속 함수입니다.

시그니처

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

type GrantPromotionRewardResult =
  | { key: string }
  | { code: string; [key: string]: unknown }
  | { errorCode: string; message: string }
  | 'ERROR'
  | undefined;

declare function grantPromotionReward(params: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardResult>;

파라미터

이름	타입	필수	설명
params	object	✓	리워드 지급 정보를 담은 래퍼 객체.
params.promotionCode	string	✓	사전에 등록된 프로모션 코드.
params.amount	number	✓	지급할 포인트 금액.

반환값

• { key: string } — 지급 성공. key는 리워드 키입니다.
• { errorCode: string; message: string } — 지급 실패. 에러 코드는 다음과 같습니다.
  • "4100" — 프로모션 정보를 찾을 수 없습니다.
  • "4104" — 프로모션이 중지되었습니다.
  • "4105" — 프로모션이 종료되었습니다.
  • "4108" — 프로모션이 승인되지 않았습니다.
  • "4109" — 프로모션이 실행 중이 아닙니다.
  • "4110" — 리워드를 지급·회수할 수 없습니다.
  • "4112" — 프로모션 머니가 부족합니다.
  • "4113" — 이미 지급·회수된 내역입니다.
  • "4114" — 프로모션에 설정된 1회 지급 금액을 초과했습니다.
• 'ERROR' — 알 수 없는 오류가 발생했습니다.
• undefined — 앱 버전이 최소 지원 버전보다 낮습니다.

권한

권한이 필요하지 않습니다. 토스 세션(계정 연결)이 처리합니다.

예제

최소 예제

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

const result = await grantPromotionReward({
  params: { promotionCode: 'PROMO_2026', amount: 1000 },
});

if (!result) {
  console.warn('앱 버전이 최소 지원 버전보다 낮습니다.');
} else if (result === 'ERROR') {
  console.error('리워드 지급 중 알 수 없는 오류가 발생했습니다.');
} else if ('key' in result) {
  console.log('리워드 지급 성공! 키:', result.key);
} else if ('errorCode' in result) {
  console.error('리워드 지급 실패:', result.errorCode, result.message);
}

실전 예제 — 버튼 클릭 시 리워드 지급

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

function RewardButton({ promotionCode }: { promotionCode: string }) {
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
  const [message, setMessage] = useState('');

  async function handleClick() {
    setStatus('loading');
    const result = await grantPromotionReward({
      params: { promotionCode, amount: 500 },
    });

    if (!result) {
      setStatus('error');
      setMessage('앱을 업데이트해 주세요.');
    } else if (result === 'ERROR') {
      setStatus('error');
      setMessage('오류가 발생했습니다. 다시 시도해 주세요.');
    } else if ('key' in result) {
      setStatus('success');
      setMessage('리워드가 지급되었습니다!');
    } else if ('errorCode' in result) {
      setStatus('error');
      setMessage(`지급 실패 (${result.errorCode}): ${result.message}`);
    }
  }

  return (
    <div>
      <button type="button" onClick={handleClick} disabled={status === 'loading'}>
        리워드 받기
      </button>
      {message && <p>{message}</p>}
    </div>
  );
}

직접 실행해 보기

sdk-example의 Game 페이지에서 grantPromotionReward 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• grantPromotionRewardForGame — (Deprecated) 게임 카테고리 전용 리워드 지급.
• getGameCenterGameProfile — 게임센터 프로필을 조회합니다.

관련 가이드

• Recipes — 프로모션 리워드 지급 패턴

외부 참조

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