Создание группы промокодов

Группа промокодов создается за один шаг — вместе с переданным набором кодов.

Процесс состоит из трех шагов:

  1. Создание группы.
  2. Добавление кодов.
  3. Сохранение группы как активной. Если на последнем шаге код конфликтует с кодом другой активной группы (в пересекающемся периоде действия), операция отменяется с ошибкой 409 Conflict.

В группе должен быть хотя бы один код.

Request

POST

https://api.kit.yandex.net/v1/promocode_groups

Body

application/json
{
  "title": "Скидка для новых клиентов",
  "discount_value": {
    "value": "10.00",
    "type": "PERCENT"
  },
  "minimum_order_amount": "1000.00",
  "max_usage": 1000,
  "max_discount_amount": "500.00",
  "one_time_use": true,
  "first_order_only": false,
  "valid_from": "2024-01-01T00:00:00Z",
  "valid_until": "2024-12-31T23:59:59Z",
  "binding_mode": "ALL_VARIANTS",
  "type": "ORDER",
  "group_type": "SINGLE",
  "show_in_pdp": false,
  "codes": [
    "WELCOME10"
  ]
}

Name

Description

binding_mode

Type: PromocodeGroupBindingMode

Режим применения скидки к товарам. Учитывается только для промокодов типа PRODUCTS:

  • ALL_VARIANTS — скидка применяется ко всем товарам магазина.
  • SELECTED_VARIANTS — скидка применяется к выбранным товарам.
  • SELECTED_CATEGORIES_COLLECTIONS — скидка применяется к товарам из выбранных категорий и коллекций.

Enum: ALL_VARIANTS, SELECTED_VARIANTS, SELECTED_CATEGORIES_COLLECTIONS

codes

Type: string[]

Список кодов промокодов. Должен содержать хотя бы один код. Каждый код — уникальная строка длиной от 3 до 20 символов (заглавные латинские буквы, цифры и спецсимволы !@#$%^&*()_-=+).

Min items: 1

Example
[
  "WELCOME10"
]

discount_value

Type: DiscountValue

Информация о значении скидки и о типе скидки.

Example
{
  "value": "10.00",
  "type": "PERCENT"
}

first_order_only

Type: boolean

Промокод применяется только к первому заказу покупателя.

Default: false

group_type

Type: PromocodeGroupType

Тип группы промокодов:

  • SINGLE — группа с одним кодом (традиционный промокод), один код на всех покупателей.
  • MULTIPLE — группа с набором кодов (каждый код предназначен для одного использования — купоны).

Enum: SINGLE, MULTIPLE

one_time_use

Type: boolean

Ограничение одноразового использования — каждый код может быть использован не более одного раза.

Default: false

show_in_pdp

Type: boolean

Показывать ли промокоды группы на странице товара. Применимо только для промокодов типа PRODUCTS.

Default: false

title

Type: string

Название группы промокодов.

Max length: 100

Example: Скидка для новых клиентов

type

Type: PromocodeGroupPromocodeType

Тип промокода — к чему применяется скидка:

  • ORDER — скидка на всю сумму заказа.
  • PRODUCTS — скидка на конкретные товары (или все товары, в зависимости от binding_mode).

Enum: ORDER, PRODUCTS

valid_from

Type: string<date-time>

Дата и время начала действия промокодов группы (RFC 3339).

Example: 2024-01-01T00:00:00Z

max_discount_amount

Type: string<decimal>

Максимальная сумма скидки за одно применение. Не передавайте поле, чтобы не ограничивать.

Example: 500.00

max_usage

Type: integer

Максимальное суммарное количество использований кодов группы. Не передавайте поле, чтобы не ограничивать.

Min value: 1

minimum_order_amount

Type: string<decimal>

Минимальная сумма заказа для применения промокода. Не передавайте поле, чтобы не устанавливать ограничение.

Example: 1000.00

valid_until

Type: string<date-time>

Дата и время окончания действия промокодов группы (RFC 3339). Не передавайте поле для бессрочного действия.

Example: 2024-12-31T23:59:59Z

DiscountValue

Информация о значении скидки и о типе скидки.

Name

Description

type

Type: string

Тип скидки:

  • PERCENT — скидка в процентах от цены товара.
  • VALUE — скидка в абсолютном значении (в рублях).

Enum: PERCENT, VALUE

value

Type: string<decimal>

  • Для типа PERCENT — значение от 0 до 100 (например, 10.5).

  • Для типа VALUE — сумма в рублях (например, 500.00).

Example: 10.00
Example
{
  "value": "10.00",
  "type": "PERCENT"
}

PromocodeGroupBindingMode

Режим применения скидки к товарам. Учитывается только для промокодов типа PRODUCTS:

  • ALL_VARIANTS — скидка применяется ко всем товарам магазина.
  • SELECTED_VARIANTS — скидка применяется к выбранным товарам.
  • SELECTED_CATEGORIES_COLLECTIONS — скидка применяется к товарам из выбранных категорий и коллекций.

Type: string

Enum: ALL_VARIANTS, SELECTED_VARIANTS, SELECTED_CATEGORIES_COLLECTIONS

PromocodeGroupPromocodeType

Тип промокода — к чему применяется скидка:

  • ORDER — скидка на всю сумму заказа.
  • PRODUCTS — скидка на конкретные товары (или все товары, в зависимости от binding_mode).

Type: string

Enum: ORDER, PRODUCTS

PromocodeGroupType

Тип группы промокодов:

  • SINGLE — группа с одним кодом (традиционный промокод), один код на всех покупателей.
  • MULTIPLE — группа с набором кодов (каждый код предназначен для одного использования — купоны).

Type: string

Enum: SINGLE, MULTIPLE

Responses

201 Created

Группа промокодов успешно создана.

Body

application/json
{
  "id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9",
  "title": "Скидка для новых клиентов",
  "discount_value": {
    "value": "10.00",
    "type": "PERCENT"
  },
  "minimum_order_amount": "1000.00",
  "max_usage": 1000,
  "max_discount_amount": "500.00",
  "one_time_use": true,
  "first_order_only": false,
  "valid_from": "2024-01-01T00:00:00Z",
  "valid_until": "2024-12-31T23:59:59Z",
  "binding_mode": "ALL_VARIANTS",
  "type": "ORDER",
  "group_type": "SINGLE",
  "show_in_pdp": false,
  "status": "ACTIVE",
  "usage_count": 42,
  "code_count": 100,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z"
}

Name

Description

binding_mode

Type: PromocodeGroupBindingMode

Режим применения скидки к товарам. Учитывается только для промокодов типа PRODUCTS:

  • ALL_VARIANTS — скидка применяется ко всем товарам магазина.
  • SELECTED_VARIANTS — скидка применяется к выбранным товарам.
  • SELECTED_CATEGORIES_COLLECTIONS — скидка применяется к товарам из выбранных категорий и коллекций.

Enum: ALL_VARIANTS, SELECTED_VARIANTS, SELECTED_CATEGORIES_COLLECTIONS

code_count

Type: integer

Количество кодов в группе.

created_at

Type: string<date-time>

Дата и время создания группы (RFC 3339).

Example: 2024-01-01T00:00:00Z

discount_value

Type: DiscountValue

Информация о значении скидки и о типе скидки.

Example
{
  "value": "10.00",
  "type": "PERCENT"
}

first_order_only

Type: boolean

Промокод применяется только к первому заказу покупателя.

group_type

Type: PromocodeGroupType

Тип группы промокодов:

  • SINGLE — группа с одним кодом (традиционный промокод), один код на всех покупателей.
  • MULTIPLE — группа с набором кодов (каждый код предназначен для одного использования — купоны).

Enum: SINGLE, MULTIPLE

id

Type: PromocodeGroupID

Уникальный идентификатор группы промокодов.

Example: 019b21d9-c5d9-777d-80bd-d67c664bc6d9

one_time_use

Type: boolean

Ограничение одноразового использования — каждый код может быть использован не более одного раза.

show_in_pdp

Type: boolean

Показывать ли промокоды группы на странице товара. Применимо только для промокодов типа PRODUCTS.

status

Type: PromocodeGroupStatus

Статус группы промокодов:

  • ACTIVE — группа активна, коды применяются при оформлении заказа.
  • INACTIVE — группа неактивна, коды не применяются.

Enum: ACTIVE, INACTIVE

title

Type: string

Название группы промокодов.

Max length: 100

Example: Скидка для новых клиентов

type

Type: PromocodeGroupPromocodeType

Тип промокода — к чему применяется скидка:

  • ORDER — скидка на всю сумму заказа.
  • PRODUCTS — скидка на конкретные товары (или все товары, в зависимости от binding_mode).

Enum: ORDER, PRODUCTS

updated_at

Type: string<date-time>

Дата и время последнего обновления группы (RFC 3339).

Example: 2024-06-01T12:00:00Z

usage_count

Type: integer

Суммарное количество использований всех кодов группы.

valid_from

Type: string<date-time>

Дата и время начала действия промокодов группы (RFC 3339).

Example: 2024-01-01T00:00:00Z

max_discount_amount

Type: string<decimal>

Максимальная сумма скидки за одно применение промокода. Если не указана — ограничений нет.

Example: 500.00

max_usage

Type: integer

Максимальное суммарное количество использований кодов группы. Если не указано — ограничений нет.

Min value: 1

minimum_order_amount

Type: string<decimal>

Минимальная сумма заказа для применения промокода. Если не указана — ограничений нет.

Example: 1000.00

valid_until

Type: string<date-time>

Дата и время окончания действия промокодов группы (RFC 3339). Если не указана — промокоды действуют бессрочно.

Example: 2024-12-31T23:59:59Z

PromocodeGroupID

Уникальный идентификатор группы промокодов.

Type: string<uuid>

Example: 019b21d9-c5d9-777d-80bd-d67c664bc6d9

PromocodeGroupStatus

Статус группы промокодов:

  • ACTIVE — группа активна, коды применяются при оформлении заказа.
  • INACTIVE — группа неактивна, коды не применяются.

Type: string

Enum: ACTIVE, INACTIVE

400 Bad Request

Некорректный запрос.

Body

application/json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input",
  "trace_id": "00000000000000000000000000000000"
}

Name

Description

code

Type: string

Example: VALIDATION_ERROR

message

Type: string

Example: Invalid input

trace_id

Type: string

Уникальный идентификатор запроса для отладки.

Example: 00000000000000000000000000000000

401 Unauthorized

Не авторизован.

Body

application/json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input",
  "trace_id": "00000000000000000000000000000000"
}

Name

Description

code

Type: string

Example: VALIDATION_ERROR

message

Type: string

Example: Invalid input

trace_id

Type: string

Уникальный идентификатор запроса для отладки.

Example: 00000000000000000000000000000000

409 Conflict

Конфликт — один или несколько кодов уже используются в другой активной группе с пересекающимся периодом действия.

Body

application/json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input",
  "trace_id": "00000000000000000000000000000000"
}

Name

Description

code

Type: string

Example: VALIDATION_ERROR

message

Type: string

Example: Invalid input

trace_id

Type: string

Уникальный идентификатор запроса для отладки.

Example: 00000000000000000000000000000000

500 Internal Server Error

Внутренняя ошибка сервера.

Body

application/json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input",
  "trace_id": "00000000000000000000000000000000"
}

Name

Description

code

Type: string

Example: VALIDATION_ERROR

message

Type: string

Example: Invalid input

trace_id

Type: string

Уникальный идентификатор запроса для отладки.

Example: 00000000000000000000000000000000
Предыдущая
Получение списка групп промокодов
Следующая
Получение группы промокодов по идентификатору