> 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/api/zh/promotion.md).

# 促销（Toss 积分）

## 创建促销奖励发放密钥

> 此 API 会发放用于让合作伙伴应用向 Toss 用户发放 Toss 积分的密钥。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明             |\
> \| --------- | -------------- |\
> \| \`4095\`       | 请求已超出限额。请稍后再试。 |\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是合作伙伴应用向 Toss 用户发放 Toss 积分时使用的 API。","name":"promotion"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"TossApiSuccessGetKeyResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/GetKeyResponse"}},"required":["resultType","success"],"type":"object"},"GetKeyResponse":{"description":"这是创建促销奖励发放密钥的响应。","properties":{"key":{"description":"这是用于发放促销奖励的加密密钥。","type":"string"}},"required":["key"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key":{"post":{"description":"此 API 会发放用于让合作伙伴应用向 Toss 用户发放 Toss 积分的密钥。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明             |\n| --------- | -------------- |\n| `4095`       | 请求已超出限额。请稍后再试。 |\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"getKey","responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessGetKeyResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessGetKeyResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"促销奖励发放密钥创建成功"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"创建促销奖励发放密钥","tags":["promotion"]}}}}
```

## 发放促销奖励

> 此 API 让合作伙伴应用可以向 Toss 用户发放 Toss 积分\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明                   |\
> \| --------- | -------------------- |\
> \| \`4000\`       | 请求无效。                |\
> \| \`4100\`       | 找不到促销信息              |\
> \| \`4108\`       | 促销未获批准               |\
> \| \`4109\`       | 促销未在执行中              |\
> \| \`4114\`       | 超过促销中设置的单次发放金额，无法发放。 |\
> \| \`4112\`       | 促销资金不足               |\
> \| \`4105\`       | 促销已结束                |\
> \| \`4113\`       | 已是发放/回收记录            |\
> \| \`4110\`      | 无法发放/回收奖励            |\
> \| \`4034\`      | 没有工作区，或者没有访问工作区的权限   |\
> \| \`4010\`      | 找不到认证信息。             |\
> \| \`4095\`      | 请求已超出限额。请稍后再试。       |\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次，每位用户每分钟 20 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是合作伙伴应用向 Toss 用户发放 Toss 积分时使用的 API。","name":"promotion"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"ExecutePromotionRequest":{"description":"这是发放促销奖励的请求。","properties":{"amount":{"description":"这是要发放给 Toss 用户的促销金额","format":"int64","type":"integer"},"key":{"description":"这是通过“创建促销奖励发放密钥”API 发放的奖励发放密钥","type":"string"},"promotionCode":{"description":"这是通过控制台创建的促销活动的促销代码","type":"string"}},"required":["amount","key","promotionCode"],"type":"object"},"TossApiSuccessExecutePromotionResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExecutePromotionResponse"}},"required":["resultType","success"],"type":"object"},"ExecutePromotionResponse":{"description":"这是发放促销奖励的响应。","properties":{"key":{"description":"这是用于发放促销奖励的密钥。","type":"string"}},"required":["key"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/promotion/execute-promotion":{"post":{"description":"此 API 让合作伙伴应用可以向 Toss 用户发放 Toss 积分\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明                   |\n| --------- | -------------------- |\n| `4000`       | 请求无效。                |\n| `4100`       | 找不到促销信息              |\n| `4108`       | 促销未获批准               |\n| `4109`       | 促销未在执行中              |\n| `4114`       | 超过促销中设置的单次发放金额，无法发放。 |\n| `4112`       | 促销资金不足               |\n| `4105`       | 促销已结束                |\n| `4113`       | 已是发放/回收记录            |\n| `4110`      | 无法发放/回收奖励            |\n| `4034`      | 没有工作区，或者没有访问工作区的权限   |\n| `4010`      | 找不到认证信息。             |\n| `4095`      | 请求已超出限额。请稍后再试。       |\n\n**请求限额**: 每个应用每分钟 3,000 次，每位用户每分钟 20 次","operationId":"executePromotion","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API 获取","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutePromotionRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessExecutePromotionResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessExecutePromotionResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"已成功向 Toss 用户发放 Toss 积分"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"发放促销奖励","tags":["promotion"]}}}}
```

## 查询促销 Toss 积分发放结果

> 此 API 让合作伙伴应用可以查询已向 Toss 用户发放的 Toss 积分\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明             |\
> \| --------- | -------------- |\
> \| \`4000\`       | 请求无效。          |\
> \| \`4100\`       | 找不到促销信息        |\
> \| \`4111\`       | 找不到奖励发放记录      |\
> \| \`4010\`       | 找不到认证信息。       |\
> \| \`4095\`       | 请求已超出限额。请稍后再试。 |\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是合作伙伴应用向 Toss 用户发放 Toss 积分时使用的 API。","name":"promotion"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"GetExecutionResultRequest":{"description":"这是查询促销执行结果的请求。","properties":{"key":{"description":"这是通过“创建促销奖励发放密钥”API 发放的奖励发放密钥","type":"string"},"promotionCode":{"description":"这是通过控制台创建的促销活动的促销代码","type":"string"}},"required":["key","promotionCode"],"type":"object"},"TossApiSuccessGetExecutionResultResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"description":"这是促销执行结果查询响应。PENDING：奖励发放请求已受理并处理中，SUCCESS：奖励发放已完成，FAILED：奖励发放请求失败，已使用的预算已回滚。","enum":["PENDING","SUCCESS","FAILED"],"type":"string"}},"required":["resultType","success"],"type":"object"},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/promotion/execution-result":{"post":{"description":"此 API 让合作伙伴应用可以查询已向 Toss 用户发放的 Toss 积分\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明             |\n| --------- | -------------- |\n| `4000`       | 请求无效。          |\n| `4100`       | 找不到促销信息        |\n| `4111`       | 找不到奖励发放记录      |\n| `4010`       | 找不到认证信息。       |\n| `4095`       | 请求已超出限额。请稍后再试。 |\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"getExecutionResult","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API 获取","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetExecutionResultRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessGetExecutionResultResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessGetExecutionResultResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"已成功查询促销发放结果"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"查询促销 Toss 积分发放结果","tags":["promotion"]}}}}
```


---

# 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/api/zh/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.