Back to Details

a1-yandex-kit-promotions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

A1 Yandex KIT — Promotions

A1 Yandex KIT — 促销管理

Communication

沟通规范

Before producing any user-facing message, read and apply 
../a1-yandex-kit/references/merchant-communication.md
 completely.
Covers the promotions domain of the Yandex KIT e-commerce API — tags: Скидки, Промокоды, Группы промокодов, Подарки. Promotions are created first and then bound to objects: discounts, promocodes and promocode groups to variants, categories or collections via their 
.../objects/add
and 
.../objects/remove
endpoints (a promocode-group request carries either variants or categories+collections, not both), gifts to variants via 
POST
/
DELETE /v1/gifts/{id}/variants
. Промокоды and Группы промокодов are separate models: a promocode is one standalone code, while a group holds the discount rules plus its codes — type 
SINGLE
(one shared code) or 
MULTIPLE
(single-use coupon codes managed via 
/v1/promocode_groups/{group_id}/codes
). End-of-life differs per kind — only discounts can be archived (
ArchiveDiscount
/
UnarchiveDiscount
, status 
ACTIVE
/
INACTIVE
/
ARCHIVED
; archived discounts stop applying but stay restorable). Promocodes and gifts have no archive endpoints and only two statuses, 
ACTIVE
/
INACTIVE
— pause them by PATCHing 
status
to 
INACTIVE
via 
UpdatePromocode
/
UpdateGift
. Promocode groups also report 
ACTIVE
/
INACTIVE
, but 
UpdatePromocodeGroup
is a full PUT replace with no 
status
field — every field is required, so resend the current values when changing anything. 
DeleteGift
removes a gift permanently, with no restore — prefer deactivation; 
DeletePromocodeGroup
likewise permanently deletes the group with all its codes.
For authentication (
Authorization: Bearer <token>
), the base URL (
https://api.kit.yandex.net
, all paths under 
/v1/
), the 3 rps rate limit and the 
{code, message, trace_id}
error contract, see the 
a1-yandex-kit
skill.
在生成任何面向用户的消息之前，请完整阅读并遵循
../a1-yandex-kit/references/merchant-communication.md
中的规范。
本文档覆盖Yandex KIT电商API的促销领域，对应标签：折扣、促销码、促销码组、赠品。促销资源需先创建，再绑定到对应对象：折扣、促销码和促销码组可通过
.../objects/add
和
.../objects/remove
端点绑定到商品变体、品类或合集（促销码组请求只能选择绑定商品变体，或绑定品类+合集，不可同时选择两者）；赠品则通过
POST
/
DELETE /v1/gifts/{id}/variants
绑定到商品变体。促销码和促销码组是独立的模型：单个促销码是独立的兑换码，而促销码组包含折扣规则及下属的兑换码——类型分为
SINGLE
（单个共享码）或
MULTIPLE
（通过
/v1/promocode_groups/{group_id}/codes
管理的一次性优惠券码）。不同类型促销资源的生命周期管理方式不同：仅支持对折扣进行归档操作（
ArchiveDiscount
/
UnarchiveDiscount
接口，状态分为
ACTIVE
/
INACTIVE
/
ARCHIVED
；已归档的折扣不再生效，但可恢复）。促销码和赠品无归档接口，仅支持
ACTIVE
/
INACTIVE
两种状态——可通过
UpdatePromocode
/
UpdateGift
接口发送PATCH请求将
status
设为
INACTIVE
来暂停生效。促销码组同样返回
ACTIVE
/
INACTIVE
状态，但
UpdatePromocodeGroup
是全量PUT替换接口，且无
status
字段——所有字段均为必填项，因此修改任何内容时需重新发送当前所有字段的值。
DeleteGift
会永久删除赠品，无法恢复——建议优先使用停用操作；
DeletePromocodeGroup
同样会永久删除促销码组及下属所有兑换码。
关于认证方式（
Authorization: Bearer <token>
）、基础URL（
https://api.kit.yandex.net
，所有路径均在
/v1/
下）、每秒3次的请求速率限制，以及
{code, message, trace_id}
格式的错误响应规范，请参考
a1-yandex-kit
技能文档。

Workflow

工作流程

Run the bundled scripts from this skill's directory — they are self-contained (Node.js >= 20, builtins + a vendored validator, no 
npm install
, no network).
  1. Search for the operation you need:
    bash
    node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]
    Matches operation ids, paths, tags and the Russian summaries/descriptions, e.g. 
    node scripts/search_docs.mjs "создать скидку"
    .
  2. Inspect the full contract of one operation — path/query parameters plus the fully dereferenced request/response schemas:
    bash
    node scripts/search_docs.mjs --operation CreateDiscount
  3. Validate a drafted request body offline before sending anything:
    bash
    node scripts/validate.mjs --operation CreateDiscount --body '<json>'
# or: node scripts/validate.mjs --operation CreateDiscount --body-file body.json
    Prints 
    VALID
    (exit 0) or the list of schema violations (exit 1).
  4. Execute the operation:
    • prefer the matching 
      mcp-yandex-kit
      MCP tool from «Related MCP tools» below (e.g. 
      create_discount
      , 
      manage_promocode_objects
      );
    • any operation without a dedicated tool: the 
      kit_request
      MCP tool — it validates the body against the same schema before sending;
    • or plain HTTP: 
      curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
      (mind the 3 rps limit).
从本技能的目录中运行内置脚本即可完成操作——脚本为独立运行模式（需Node.js >=20，仅依赖内置模块及本地验证器，无需执行
npm install
，无需网络连接）。
  1. 搜索所需操作：
    bash
    node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]
    该脚本会匹配操作ID、路径、标签及俄文摘要/描述，例如：
    node scripts/search_docs.mjs "создать скидку"
    。
  2. 查看单个操作的完整契约——包括路径/查询参数，以及完全解引用的请求/响应 schema：
    bash
    node scripts/search_docs.mjs --operation CreateDiscount
  3. 离线验证已草拟的请求体，再发送请求：
    bash
    node scripts/validate.mjs --operation CreateDiscount --body '<json>'
# 或：node scripts/validate.mjs --operation CreateDiscount --body-file body.json
    验证通过时输出
    VALID
    （退出码0），否则输出schema违规列表（退出码1）。
  4. 执行操作：
    • 优先使用下方「相关MCP工具」中对应的
      mcp-yandex-kit
      工具（例如
      create_discount
      、
      manage_promocode_objects
      ）；
    • 无专用工具的操作：使用
      kit_request
      MCP工具——该工具会在发送前验证请求体是否符合schema；
    • 或使用原生HTTP请求： 
      curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
      （注意每秒3次的请求速率限制）。

Endpoints (39 operations)

端点（共39个操作）

Скидки

折扣

MethodPathOperationIdSummary (RU)
GET
/v1/discounts
GetDiscounts
Получение списка скидок
POST
/v1/discounts
CreateDiscount
Создание скидки
GET
/v1/discounts/{id}
GetDiscountById
Получение скидки по ID
PATCH
/v1/discounts/{id}
UpdateDiscount
Обновление скидки
GET
/v1/discounts/{id}/categories
GetDiscountCategoryIDs
Получение идентификаторов категорий для которых применяется скидка
GET
/v1/discounts/{id}/collections
GetDiscountCollectionIDs
Получение идентификаторов коллекций, к которым применяется скидка.
GET
/v1/discounts/{id}/variants
GetDiscountVariantIDs
Получение уникальных идентификаторов товаров скидки
POST
/v1/discounts/{id}/archive
ArchiveDiscount
Архивация скидки
POST
/v1/discounts/{id}/unarchive
UnarchiveDiscount
Разархивация скидки
POST
/v1/discounts/{id}/objects/add
AddDiscountObjects
Добавление объектов в скидку
POST
/v1/discounts/{id}/objects/remove
RemoveDiscountObjects
Удаление объектов из скидки
方法路径操作ID摘要
GET
/v1/discounts
GetDiscounts
获取折扣列表
POST
/v1/discounts
CreateDiscount
创建折扣
GET
/v1/discounts/{id}
GetDiscountById
根据ID获取折扣
PATCH
/v1/discounts/{id}
UpdateDiscount
更新折扣
GET
/v1/discounts/{id}/categories
GetDiscountCategoryIDs
获取折扣适用的品类ID列表
GET
/v1/discounts/{id}/collections
GetDiscountCollectionIDs
获取折扣适用的合集ID列表
GET
/v1/discounts/{id}/variants
GetDiscountVariantIDs
获取折扣适用的商品变体ID列表
POST
/v1/discounts/{id}/archive
ArchiveDiscount
归档折扣
POST
/v1/discounts/{id}/unarchive
UnarchiveDiscount
取消归档折扣
POST
/v1/discounts/{id}/objects/add
AddDiscountObjects
为折扣添加绑定对象
POST
/v1/discounts/{id}/objects/remove
RemoveDiscountObjects
移除折扣的绑定对象

Промокоды

促销码

MethodPathOperationIdSummary (RU)
GET
/v1/promocodes/{id}
GetPromocodeById
Получение промокода по уникальному идентификатору
PATCH
/v1/promocodes/{id}
UpdatePromocode
Обновление промокода
GET
/v1/promocodes
GetPromocodes
Получение списка промокодов
POST
/v1/promocodes
CreatePromocode
Создание промокода
GET
/v1/promocodes/{id}/categories
GetPromocodeCategoryIDs
Получение идентификаторов категорий, к которым применяется промокод
GET
/v1/promocodes/{id}/collections
GetPromocodeCollectionIDs
Получение идентификаторов коллекций, к которым применяется промокод
GET
/v1/promocodes/{id}/variants
GetPromocodeVariantIDs
Получение уникальных идентификаторов товаров промокода
POST
/v1/promocodes/{id}/objects/add
AddPromocodeObjects
Добавление объектов в промокод
POST
/v1/promocodes/{id}/objects/remove
RemovePromocodeObjects
Удаление объектов из промокода
方法路径操作ID摘要
GET
/v1/promocodes/{id}
GetPromocodeById
根据唯一ID获取促销码
PATCH
/v1/promocodes/{id}
UpdatePromocode
更新促销码
GET
/v1/promocodes
GetPromocodes
获取促销码列表
POST
/v1/promocodes
CreatePromocode
创建促销码
GET
/v1/promocodes/{id}/categories
GetPromocodeCategoryIDs
获取促销码适用的品类ID列表
GET
/v1/promocodes/{id}/collections
GetPromocodeCollectionIDs
获取促销码适用的合集ID列表
GET
/v1/promocodes/{id}/variants
GetPromocodeVariantIDs
获取促销码适用的商品变体ID列表
POST
/v1/promocodes/{id}/objects/add
AddPromocodeObjects
为促销码添加绑定对象
POST
/v1/promocodes/{id}/objects/remove
RemovePromocodeObjects
移除促销码的绑定对象

Группы промокодов

促销码组

MethodPathOperationIdSummary (RU)
GET
/v1/promocode_groups
GetPromocodeGroups
Получение списка групп промокодов
POST
/v1/promocode_groups
CreatePromocodeGroup
Создание группы промокодов
GET
/v1/promocode_groups/{id}
GetPromocodeGroupByID
Получение группы промокодов по идентификатору
PUT
/v1/promocode_groups/{id}
UpdatePromocodeGroup
Обновление группы промокодов
DELETE
/v1/promocode_groups/{id}
DeletePromocodeGroup
Удаление группы промокодов
POST
/v1/promocode_groups/{id}/objects/add
AddPromocodeGroupObjects
Привязка объектов к группе промокодов
POST
/v1/promocode_groups/{id}/objects/remove
RemovePromocodeGroupObjects
Отвязка объектов от группы промокодов
GET
/v1/promocode_groups/{group_id}/codes
GetPromocodeGroupCodes
Получение списка кодов в группе промокодов
POST
/v1/promocode_groups/{group_id}/codes
AddPromocodeGroupCode
Добавление кода в группу промокодов
PATCH
/v1/promocode_groups/{group_id}/codes/{code_id}
UpdatePromocodeGroupCode
Обновление кода в группе промокодов
DELETE
/v1/promocode_groups/{group_id}/codes/{code_id}
DeletePromocodeGroupCode
Удаление кода из группы промокодов
方法路径操作ID摘要
GET
/v1/promocode_groups
GetPromocodeGroups
获取促销码组列表
POST
/v1/promocode_groups
CreatePromocodeGroup
创建促销码组
GET
/v1/promocode_groups/{id}
GetPromocodeGroupByID
根据ID获取促销码组
PUT
/v1/promocode_groups/{id}
UpdatePromocodeGroup
更新促销码组
DELETE
/v1/promocode_groups/{id}
DeletePromocodeGroup
删除促销码组
POST
/v1/promocode_groups/{id}/objects/add
AddPromocodeGroupObjects
为促销码组绑定对象
POST
/v1/promocode_groups/{id}/objects/remove
RemovePromocodeGroupObjects
解除促销码组的对象绑定
GET
/v1/promocode_groups/{group_id}/codes
GetPromocodeGroupCodes
获取促销码组内的兑换码列表
POST
/v1/promocode_groups/{group_id}/codes
AddPromocodeGroupCode
为促销码组添加兑换码
PATCH
/v1/promocode_groups/{group_id}/codes/{code_id}
UpdatePromocodeGroupCode
更新促销码组内的兑换码
DELETE
/v1/promocode_groups/{group_id}/codes/{code_id}
DeletePromocodeGroupCode
删除促销码组内的兑换码

Подарки

赠品

MethodPathOperationIdSummary (RU)
GET
/v1/gifts
GetGifts
Получение списка подарков
POST
/v1/gifts
CreateGift
Создание подарка
GET
/v1/gifts/{id}
GetGiftById
Получение подарка по ID
PATCH
/v1/gifts/{id}
UpdateGift
Обновление подарка
DELETE
/v1/gifts/{id}
DeleteGift
Удаление подарка
GET
/v1/gifts/{id}/variants
GetGiftVariants
Получение идентификаторов товаров подарка
POST
/v1/gifts/{id}/variants
AddGiftVariants
Добавление товаров в подарок
DELETE
/v1/gifts/{id}/variants
RemoveGiftVariants
Удаление товаров из подарка
方法路径操作ID摘要
GET
/v1/gifts
GetGifts
获取赠品列表
POST
/v1/gifts
CreateGift
创建赠品
GET
/v1/gifts/{id}
GetGiftById
根据ID获取赠品
PATCH
/v1/gifts/{id}
UpdateGift
更新赠品
DELETE
/v1/gifts/{id}
DeleteGift
删除赠品
GET
/v1/gifts/{id}/variants
GetGiftVariants
获取赠品适用的商品变体ID列表
POST
/v1/gifts/{id}/variants
AddGiftVariants
为赠品添加商品变体
DELETE
/v1/gifts/{id}/variants
RemoveGiftVariants
移除赠品的商品变体

Related MCP tools

相关MCP工具

Curated 
mcp-yandex-kit
tools for these tags (the server also exposes the meta trio — 
search_operations
, 
get_operation_schema
, 
kit_request
— reaching all 162 operations):
  • list_discounts
    — List discounts of the store filtered by status (paginated).
  • get_discount
    — Get a single discount by its ID (title, value, dates, status, binding mode).
  • create_discount
    — Create a new discount.
  • update_discount
    — Update an existing discount (plain application/json PATCH): send only the fields to change (title, discount_value, discount_dates, status, binding_mode).
  • discount_action
    — Archive a discount (soft delete: status becomes ARCHIVED, the discount stops applying but stays restorable) or unarchive it (returns it to a non-archived status).
  • manage_discount_objects
    — Attach objects to a discount or detach them.
  • list_promocodes
    — List promocodes of the store filtered by status (paginated).
  • get_promocode
    — Get a single promocode by its ID (code, title, discount value, dates, type, usage limits).
  • create_promocode
    — Create a new promocode.
  • update_promocode
    — Update an existing promocode (plain application/json PATCH): send only the fields to change (code, title, discount_value, promocode_dates, status, binding_mode, limits).
  • manage_promocode_objects
    — Attach objects to a promocode or detach them.
Подарки (gifts) and Группы промокодов have no dedicated tools — manage them through 
search_operations
+ 
kit_request
.
以下是为上述标签整理的
mcp-yandex-kit
工具（服务器还提供三个通用工具——
search_operations
、
get_operation_schema
、
kit_request
——可覆盖全部162个操作）：
  • list_discounts
    — 按状态筛选店铺折扣列表（支持分页）。
  • get_discount
    — 根据ID获取单个折扣信息（标题、折扣值、生效日期、状态、绑定模式）。
  • create_discount
    — 创建新折扣。
  • update_discount
    — 更新现有折扣（标准application/json PATCH请求）：仅发送需要修改的字段（标题、折扣值、折扣生效日期、状态、绑定模式）。
  • discount_action
    — 归档折扣（软删除：状态变为ARCHIVED，折扣不再生效但可恢复）或取消归档（恢复为非归档状态）。
  • manage_discount_objects
    — 为折扣绑定或解绑对象。
  • list_promocodes
    — 按状态筛选店铺促销码列表（支持分页）。
  • get_promocode
    — 根据ID获取单个促销码信息（兑换码、标题、折扣值、生效日期、类型、使用限制）。
  • create_promocode
    — 创建新促销码。
  • update_promocode
    — 更新现有促销码（标准application/json PATCH请求）：仅发送需要修改的字段（兑换码、标题、折扣值、促销码生效日期、状态、绑定模式、限制条件）。
  • manage_promocode_objects
    — 为促销码绑定或解绑对象。
赠品和促销码组暂无专用工具——需通过
search_operations
+ 
kit_request
进行管理。