Skip to main content

grantPromotionReward

Grants a point reward to the user using a promotion code. Available in all mini-app categories. Successor to the deprecated grantPromotionRewardForGame.

Signature​

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>;

Parameters​

NameTypeRequiredDescription
paramsobject✓Wrapper object containing reward details.
params.promotionCodestring✓The pre-registered promotion code.
params.amountnumber✓Points to grant.

Returns​

  • { key: string } — Grant succeeded. key is the reward key.
  • { errorCode: string; message: string } — Grant failed. Error codes:
    • "4100" — Promotion not found.
    • "4104" — Promotion is paused.
    • "4105" — Promotion has ended.
    • "4108" — Promotion is not approved.
    • "4109" — Promotion is not active.
    • "4110" — Reward cannot be granted or revoked.
    • "4112" — Insufficient promotion funds.
    • "4113" — Already granted or revoked.
    • "4114" — Exceeds the per-grant amount limit.
  • 'ERROR' — Unknown error.
  • undefined — App version is below the minimum supported version.

Permission​

No permission required. Account binding is handled by the Toss session.

Examples​

Minimal​

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

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

if (!result) {
  console.warn('App version is below the minimum supported version.');
} else if (result === 'ERROR') {
  console.error('Unknown error while granting reward.');
} else if ('key' in result) {
  console.log('Reward granted! Key:', result.key);
} else if ('errorCode' in result) {
  console.error('Grant failed:', result.errorCode, result.message);
}

Realistic — reward button with feedback​

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('Please update the Toss app.');
    } else if (result === 'ERROR') {
      setStatus('error');
      setMessage('An error occurred. Please try again.');
    } else if ('key' in result) {
      setStatus('success');
      setMessage('Reward granted!');
    } else if ('errorCode' in result) {
      setStatus('error');
      setMessage(`Grant failed (${result.errorCode}): ${result.message}`);
    }
  }

  return (
    <div>
      <button type="button" onClick={handleClick} disabled={status === 'loading'}>
        Claim reward
      </button>
      {message && <p>{message}</p>}
    </div>
  );
}

Try it live​

Run the grantPromotionReward card on the Game page in sdk-example.

Open in sdk-example

External references​