> 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/api-and-sdk-en/common/growth/promotion.md).

# Promotions

For service introduction and console setup, please refer to [the promotion introduction document](https://developers-apps-in-toss.toss.im/guide/marketing/promotion).

{% hint style="info" %}
**Please be sure to check before developing a promotion**

To prevent user confusion, you cannot use the same name as one already used in Toss or use it with a different meaning.

**\[Example]**

* **Points**
  * For proprietary rewards used within the mini app, **'Points'** cannot be used as a name.
    * It may be mistaken as having been paid as 'Toss Points.'
  * Please use a term that can be clearly distinguished from 'Toss Points.'
* **Withdrawal, cash-out, etc.** — Terms that could be mistaken for cashing out cannot be used.
  * If virtual assets within the mini app are converted into 'Toss Points,' **'Toss Points issued'** please label it as.
    {% endhint %}

{% hint style="info" %}
**Call limit**

You can call up to 10 times per minute per userKey. If exceeded, an error is returned.
{% endhint %}

***

### Game mini app

Even without separate server integration, **You can issue Toss Points to users within the game mini app**and display them in the Benefits tab.

**SDK function: `grantPromotionRewardForGame`**

This function can only be called from mini apps in the game category. An error occurs if it is run in a non-game category.

{% hint style="info" %}
**Caution**

* **Toss app version 5.232.0 or later**is supported. In versions earlier than that, `undefined`is returned, and an update notice screen is shown when entering the mini app.
* To securely obtain identifiers for all users, **we raised the minimum supported version of the Toss app to 5.232.0**.
* The game user identifier is **an internal key for the game company**and can only be used as such; you cannot directly request Toss servers with this key.
* If you call the function multiple times, rewards may be issued multiple times to the same user, **so be sure to apply defensive logic**.
* **Before starting the actual promotion, call at least once with a test promotion code**You need to. (Through the test call, the promotion is properly registered and moved to approved status.)
  {% endhint %}

**Signature**

```typescript
function grantPromotionRewardForGame({
  params,
}: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardForGameResult>;
```

**Parameters**

* **params** · Required · `{ params: { promotionCode: string; amount: number } }`

  This is the information needed to issue points.

  * **params.promotionCode** · Required · `string`

    Promotion code.
  * **params.amount** · Required · `number`

    Amount of points to issue.

**Return value**

* `Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>`

Returns the point issuance result.

* `{ key: string }`: Point issuance succeeded. key means the reward key.
* `{ errorCode: string, message: string }`: Point issuance failed. Please check the error code.

**Error code**

This is the list of error codes that can occur while using the promotion function. Refer to the response code or message and **appropriate exception handling logic**please apply it.

{% hint style="info" %}
**`4109` What if an error occurs?**

* of the promotion budget **80% depletion email notification**is sent.
* To continue the promotion, **increase the budget in the console**.
* If the budget is insufficient, **top up the amount in Biz Wallet**to increase the budget.
* When the budget is fully exhausted, the promotion **automatically ends, `4109` an error occurs**.
* If point issuance fails due to insufficient budget, **please note that it can lead to user CS issues**.
  {% endhint %}

| Code        | Message                                                      | Cause / response method                                                                                           |
| ----------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `40000`     |                                                              | When called from a non-game mini app                                                                              |
| `4100`      | Promotion information cannot be found                        | When called with a promotion key not registered in the console                                                    |
| `4109`      | The promotion is not running                                 | When the promotion was not started in the console, or was automatically terminated after the budget was exhausted |
| `4110`      | Rewards cannot be issued/withdrawn                           | In cases where an internal system error occurred, **reissue logic**please apply it.                               |
| `4111`      | Reward issuance history cannot be found                      | When querying a non-existent issuance record                                                                      |
| `4112`      | Insufficient promotion money                                 | When issuance failed due to insufficient budget, increase the budget in the console or top up Biz Wallet          |
| `4114`      | Exceeded the one-time issuance amount                        |                                                                                                                   |
| `4116`      | The maximum issuance amount exceeded the budget              |                                                                                                                   |
| `ERROR`     | An unknown error occurred.                                   |                                                                                                                   |
| `undefined` | The app version is lower than the minimum supported version. |                                                                                                                   |

**Example**

{% tabs %}
{% tab title="js" %}

```js
import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

async function handleGrantPromotionRewardForGame() {
  const result = await grantPromotionRewardForGame({
    params: {
      promotionCode: 'GAME_EVENT_2024',
      amount: 1000,
    },
  });

  if (!result) {
    console.warn('This app version is not supported.');
  } else if (result === 'ERROR') {
    console.error('An unknown error occurred while issuing points.');
  } else if ('key' in result) {
    console.log('Point issuance succeeded!', result.key);
  } else if ('errorCode' in result) {
    console.error('Point issuance failed:', result.errorCode, result.message);
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

function GrantRewardButton() {
  async function handleClick() {
    const result = await grantPromotionRewardForGame({
      params: {
        promotionCode: 'GAME_EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An unknown error occurred while issuing points.');
      return;
    }

    if ('key' in result) {
      console.log('Point issuance succeeded!', result.key);
    } else if ('errorCode' in result) {
      console.error('Point issuance failed:', result.errorCode, result.message);
    }
  }

  return <button onClick={handleClick}>Issue Points</button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Button } from 'react-native';
import { grantPromotionRewardForGame } from '@apps-in-toss/framework';

function GrantRewardButton() {
  async function handlePress() {
    const result = await grantPromotionRewardForGame({
      params: {
        promotionCode: 'GAME_EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An unknown error occurred while issuing points.');
      return;
    }

    if ('key' in result) {
      console.log('Point issuance succeeded!', result.key);
    } else if ('errorCode' in result) {
      console.error('Point issuance failed:', result.errorCode, result.message);
    }
  }

  return <Button onPress={handlePress} title="Issue Points" />;
}
```

{% endtab %}
{% endtabs %}

***

### Non-game mini app

There are two ways to issue Toss Points to users through promotions in non-game category mini apps.

* **Issue without a server**: Issue points only by calling the SDK function without separate server integration.
* **Issue through the server**: Issue points by directly calling the API from the partner company's server. Use this when integrity is important, such as preventing request tampering.

#### Issue promotional points without a server

**SDK function: `grantPromotionReward`**

Even without separate server integration, **You need to issue Toss Points to users within a non-game mini app**and display them in the Benefits tab.

{% hint style="info" %}
**Caution**

* **Toss app version 5.232.0 or later**is supported. In versions earlier than that, `undefined`is returned, and an update notice screen is shown when entering the mini app.
* If you call the function multiple times, rewards may be issued multiple times to the same user, **so be sure to apply defensive logic**.
* **Before starting the actual promotion, call at least once with a test promotion code**Must be called. The test promotion code is not for the sandbox app, **Toss app (QR code test)** you must call it in.
  {% endhint %}

**Signature**

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

**Parameters**

* **params** · Required · `{ params: { promotionCode: string; amount: number } }`

  This is the information needed to issue points.

  * **params.promotionCode** · Required · `string`

    Promotion code.
  * **params.amount** · Required · `number`

    Amount of points to issue.

**Return value**

* `Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>`

Returns the point issuance result.

* `{ key: string }`: Point issuance succeeded. key means the reward key.
* `{ errorCode: string, message: string }`: Point issuance failed. Please check the error code.

**Error code**

This is the list of error codes that can occur while using the promotion function. Refer to the response code or message and **appropriate exception handling logic**please apply it.

{% hint style="info" %}
**`4109` What if an error occurs?**

* of the promotion budget **80% depletion email notification**is sent.
* To continue the promotion, **increase the budget in the console**.
* If the budget is insufficient, **top up the amount in Biz Wallet**to increase the budget.
* When the budget is fully exhausted, the promotion **automatically ends, `4109` an error occurs**.
* If point issuance fails due to insufficient budget, **please note that it can lead to user CS issues**.
  {% endhint %}

| Code        | Message                                                      | Cause / response method                                                                                           |
| ----------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `4100`      | Promotion information cannot be found                        | When called with a promotion key not registered in the console                                                    |
| `4109`      | The promotion is not running                                 | When the promotion was not started in the console, or was automatically terminated after the budget was exhausted |
| `4110`      | Rewards cannot be issued/withdrawn                           | In cases where an internal system error occurred, **reissue logic**please apply it.                               |
| `4111`      | Reward issuance history cannot be found                      | When querying a non-existent issuance record                                                                      |
| `4112`      | Insufficient promotion money                                 | When issuance failed due to insufficient budget, increase the budget in the console or top up Biz Wallet          |
| `4114`      | Exceeded the one-time issuance amount                        |                                                                                                                   |
| `4116`      | The maximum issuance amount exceeded the budget              |                                                                                                                   |
| `ERROR`     | An unknown error occurred.                                   |                                                                                                                   |
| `undefined` | The app version is lower than the minimum supported version. |                                                                                                                   |

**Example**

{% tabs %}
{% tab title="js" %}

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

async function handleGrantPromotionReward() {
  const result = await grantPromotionReward({
    params: {
      promotionCode: 'EVENT_2024',
      amount: 1000,
    },
  });

  if (!result) {
    console.warn('This app version is not supported.');
  } else if (result === 'ERROR') {
    console.error('An unknown error occurred while issuing points.');
  } else if ('key' in result) {
    console.log('Point issuance succeeded!', result.key);
  } else if ('errorCode' in result) {
    console.error('Point issuance failed:', result.errorCode, result.message);
  }
}
```

{% endtab %}

{% tab title="React" %}

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

function GrantRewardButton() {
  async function handleClick() {
    const result = await grantPromotionReward({
      params: {
        promotionCode: 'EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An unknown error occurred while issuing points.');
      return;
    }

    if ('key' in result) {
      console.log('Point issuance succeeded!', result.key);
    } else if ('errorCode' in result) {
      console.error('Point issuance failed:', result.errorCode, result.message);
    }
  }

  return <button onClick={handleClick}>Issue Points</button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Button } from 'react-native';
import { grantPromotionReward } from '@apps-in-toss/framework';

function GrantRewardButton() {
  async function handlePress() {
    const result = await grantPromotionReward({
      params: {
        promotionCode: 'EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An unknown error occurred while issuing points.');
      return;
    }

    if ('key' in result) {
      console.log('Point issuance succeeded!', result.key);
    } else if ('errorCode' in result) {
      console.error('Point issuance failed:', result.errorCode, result.message);
    }
  }

  return <Button onPress={handlePress} title="Issue Points" />;
}
```

{% endtab %}
{% endtabs %}

***

#### Issue promotional points through the server

This is a method of issuing Toss Points to users by directly calling the API from the partner company's server.

#### Identify the promotion target user

The promotion API identifies the promotion target using one of the two methods below. Do not pass both values at the same time; choose only one.

| Category          | Issuance method                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-toss-user-key` | [Toss login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained from `userKey` value.               |
| `x-anon-key`      | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)hash value obtained from |

Please choose according to your purpose.

* If you have already integrated Toss Login, or if you want to manage member information such as name and email together, use Toss Login.
* If you want to identify only the user lightly without login integration, use the user identification key issuance feature.

`x-anon-key`If you want to check in advance whether the (hash) is a valid value, [Please use the Identify Key Validation](/documentation/api-and-sdk-en/common/authentication/hash-key.md#undefined-4) API.

***

#### Basic information

| Item                  | Value                              |
| --------------------- | ---------------------------------- |
| Base URL              | `https://apps-in-toss-api.toss.im` |
| Server authentication | mTLS (client certificate)          |
| Content-Type          | `application/json`                 |

{% hint style="info" %}
**mTLS certificate is required for server-to-server communication**

The promotion API is server-to-server communication from the partner server to the Apps in Toss server. For security, configure an mTLS certificate on the server before making the call. For how to issue a certificate, [mTLS certificate issuance method](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started)please refer to
{% endhint %}

#### ① Create a promotion reward issuance key

Issue a key for promotion payment. You can use this key to issue rewards to users.

{% hint style="info" %}
**Please note**

* The partner company is the entity that issues rewards to users. If you issue rewards to users with the issued key, **within the promotion budget limit** they will be issued continuously.

* **Allow only one issuance**If you want to,

* If you try to issue again with an already used issuance key `4113` an error occurs. If additional issuance is needed, **issue a new key**.

* Issued **The validity period of the key is 1 hour**.
  {% endhint %}

* Content-type: application/json

* Method: `POST`

* Endpoint: `/api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key`

**Request headers**

For the headers that identify the promotion target, use one of the two below. Do not pass both headers at the same time.

| Name              | Type   | Required   | Description                                                                                                                                                                                                                                                                     |
| ----------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | Choose one | [Toss login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info |
| `x-anon-key`      | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value.                                                                                                                             |

**Response parameters**

| Name | Type   | Description                                            |
| ---- | ------ | ------------------------------------------------------ |
| key  | String | Key value for promotion payment (base64 encoded value) |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}
```

#### ② Issue promotion rewards

With the issued key **execute promotion reward issuance**It will be deducted from the promotion budget when issued, and there may be a slight delay until the actual issuance.

* Content-type: application/json
* Method: `POST`
* Endpoint: `/api-partner/v1/apps-in-toss/promotion/execute-promotion`

**Request headers**

For the headers that identify the promotion target, use one of the two below. Do not pass both headers at the same time.

| Name              | Type   | Required   | Description                                                                                                                                                                                                                                                                     |
| ----------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | Choose one | [Toss login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info |
| `x-anon-key`      | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value.                                                                                                                             |

**Request parameters**

| Name          | Type    | Required | Description                              |
| ------------- | ------- | -------- | ---------------------------------------- |
| promotionCode | String  | Y        | Promotion code ID created in the console |
| key           | String  | Y        | KEY issued for promotion payment         |
| amount        | Integer | Y        | Promotion payment amount                 |

```json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0=",
  "amount": 10
}
```

**Response parameters**

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| key  | String | KEY issued for promotion payment |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}
```

#### ③ Check promotion issuance result

After the issuance request, **query the promotion issuance status**.

* Content-type: application/json
* Method: `POST`
* Endpoint: `/api-partner/v1/apps-in-toss/promotion/execution-result`

**Request headers**

For the headers that identify the promotion target, use one of the two below. Do not pass both headers at the same time.

| Name              | Type   | Required   | Description                                                                                                                                                                                                                                                                     |
| ----------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | Choose one | [Toss login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info |
| `x-anon-key`      | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value.                                                                                                                             |

**Request parameters**

| Name          | Type   | Required | Description                              |
| ------------- | ------ | -------- | ---------------------------------------- |
| promotionCode | String | Y        | Promotion code ID created in the console |
| key           | String | Y        | KEY issued for promotion payment         |

```json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
}
```

**Response parameters**

| Name    | Type   | Description                                                  |
| ------- | ------ | ------------------------------------------------------------ |
| success | String | Promotion issuance result (`SUCCESS` / `PENDING` / `FAILED`) |

```json
{
  "resultType": "SUCCESS",
  "success": "PENDING"
}
```

**Error code**

This is the list of error codes that can occur while using the promotion API. Refer to the response code or message and **appropriate exception handling logic**please apply it.

{% hint style="info" %}
**`4109` What if an error occurs?**

* of the promotion budget **80% depletion email notification**is sent.
* To continue the promotion, **increase the budget in the console**.
* If the budget is insufficient, **top up the amount in Biz Wallet**to increase the budget.
* When the budget is fully exhausted, the promotion **automatically ends, `4109` an error occurs**.
* If point issuance fails due to insufficient budget, **please note that it can lead to user CS issues**.
  {% endhint %}

| Code   | Message                                         | Cause / response method                                                                                           |
| ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `4100` | Promotion information cannot be found           | When called with a promotion key not registered in the console                                                    |
| `4109` | The promotion is not running                    | When the promotion was not started in the console, or was automatically terminated after the budget was exhausted |
| `4110` | Rewards cannot be issued/withdrawn              | In cases where an internal system error occurred, **reissue logic**please apply it.                               |
| `4111` | Reward issuance history cannot be found         | When querying a non-existent issuance record                                                                      |
| `4112` | Insufficient promotion money                    | When issuance failed due to insufficient budget, increase the budget in the console or top up Biz Wallet          |
| `4113` | History has already been issued/withdrawn       | In case of duplicate issuance with the same key, please issue a new key and try again.                            |
| `4114` | Exceeded the one-time issuance amount           |                                                                                                                   |
| `4116` | The maximum issuance amount exceeded the budget |                                                                                                                   |


---

# 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/api-and-sdk-en/common/growth/promotion.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.