> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/promotion/promotion.grantreward.md).

# Promotion.grantReward

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

### 기능 설명

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

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

### 타입

```ts
Promotion.grantReward(params: { promotionCode: string; amount: number }): Promise<GrantPromotionRewardResponse | { errorCode: string; message: string } | "ERROR">;
```

**Params**

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

**Response**

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

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

### 에러

포인트 지급에 실패하면 reject되지 않고 `{ errorCode: string; message: string }` 형태의 값 또는 `'ERROR'` 문자열이 반환돼요.

* `{ errorCode: string; message: string }`: 포인트 지급에 실패했어요. `errorCode` 값은 다음과 같아요.
  * `"4100"`: 프로모션 정보를 찾을 수 없는 경우예요.
  * `"4104"`: 프로모션이 중지된 경우예요.
  * `"4105"`: 프로모션이 종료된 경우예요.
  * `"4108"`: 프로모션이 승인되지 않은 경우예요.
  * `"4109"`: 프로모션이 실행중이 아닌 경우예요.
  * `"4110"`: 리워드를 지급/회수할 수 없는 경우예요.
  * `"4112"`: 프로모션 머니가 부족한 경우예요.
  * `"4113"`: 이미 지급/회수된 내역인 경우예요.
  * `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과한 경우예요.
* `'ERROR'`: 알 수 없는 오류가 발생했어요.

에러 코드는 catch한 에러의 `error.code` 값이에요.

| 코드                        | 설명                                                                                                                                      |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `UNSUPPORTED_APP_VERSION` | 실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. `Promotion.grantReward.isSupported()`로 사전 확인하고, 발생 시 `error.message`(업데이트 안내 문구)를 사용자에게 보여주세요. |

### 예시 코드

```js
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,
    });

    if (result === "ERROR") {
      console.error("포인트 지급 중 알 수 없는 오류가 발생했어요.");
      return;
    }

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/promotion/promotion.grantreward.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.