Акции

API позволяет автоматизировать работу с акциями: находить доступные акции и условия участия, подбирать подходящие товары и управлять их участием — добавлять в акции, удалять и переключать между вариантами с разной скидкой.

Детали полей и значений смотрите в справочнике по ссылке на метод.

Идентификатор товара в акциях — это пара parentSku + country; один parentSku участвует независимо в разных странах. На данный момент акции работают только с товарами RU — передавайте country: RU.

Товар может находиться только в одном варианте акции. Чтобы переключить — сначала удалите из текущего варианта, потом добавьте в целевой.

Все цены в ответах — в копейках (amount: 680000 = 6800,00 ₽). Добавление и удаление товаров не мгновенны — обработка занимает несколько минут.

Как устроено

Промоакции в API устроены следующим образом:

• Акция (promotionId) — название, период, тип, сроки добавления и удаления товаров. Просмотр товаров в акции — по promotionId.
• Вариант акции (promotionVariantId) — конкретный набор условий: процент скидки, ограничения по категориям, полу, бизнес-модели, минимальной цене. Добавление и удаление товаров в варианте акции — по promotionVariantId.

Тип акции (type):

• ONSITE — фиксированная скидка;
• ONSITE_FLOAT — плавающая скидка, диапазон discountMinPercent…discountMaxPercent;
• COUPON — купонная скидка.

Сроки и флаги жизненного цикла акции:

• addProductsFromDate / addProductsToDate — окно, когда можно добавлять товары;
• deleteProductsToDate — до какого момента можно удалять;
• isRegistrationClosed — добавление товаров уже закрыто;
• deletedAt — акция мягко удалена: видна в списке, но управлять товарами нельзя.

Порядок работы

1. Получение списка акций и вариантов

• GET /v2/promotions — список акций и варианты. Отсюда берутся promotionId (promotions[].id) и promotionVariantId (promotions[].promotionVariants[].promotionVariantId). По умолчанию (finished=false) возвращаются незавершённые акции — поле status: IDLE (создана, но не открыта), OPEN (открыта для регистрации), PLANNED (запланирована), ACTIVE (активна). Для завершённых (PASSED, FINISHED) — finished=true.

2. Просмотр товаров в акции

• GET /v2/promotions/{promotionId}/products — товары, уже добавленные в акцию. Поле promotionVariantId у каждого товара показывает, в каком варианте он сейчас. Поддерживает пагинацию и сортировку (sort=-lamodaDiscountPercent). Учтите: состав обновляется с задержкой в несколько минут.

3. Подбор товаров для варианта акции

• GET /v2/promotion-variants/{promotionVariantId}/available-products — товары, подходящие для варианта. Подготовительный шаг перед добавлением: показывает, какие товары можно добавить, какие требуют изменения цены и какие уже в смежном варианте.

4. Добавление товаров в вариант акции

• POST /v2/promotion-variants/{promotionVariantId}/products — добавить товары в вариант. В теле — sellerId и products[] (каждый — { parentSku, country }, country: RU). Всегда проверяйте результат валидации в ответе: товар может не пройти по категории, стране, цене или периоду скидки.

5. Удаление товаров из вариантов акции

• POST /v2/promotion-variants/{promotionVariantId}/remove-products — удалить товары из варианта.

Переключение между вариантами осуществляется чере удаление товаров из текущего варианта методом выше и последующим добавлением в целевой вариант (шаг 4). Товар может находиться только в одном варианте.

Особенности

• Акции доступны только для RU-товаров — country: RU в добавлении/удалении.
• Валидация акционных цен: если isFraudThresholdExceeded=true → необходимо снизить цену до recommendedRedPrice/recommendedBlackPrice.
• Цены на товары всегда в копейках;
• Операции добавление/удаление товаров в вариант акции являются асихронными (до несколько минут) — всегда сверяйте состав акции (см. Шаг 2).
• Связь с ценами и force: если цена нарушает условия акции со статусом WARNING, force=true в методах цен может обновить цену и удалить товар из акции; при RESTRICTION принудительное обновление невозможно.

См. также

• Каталог: карточки товаров и цены
• Вопросы покупателей о товарах
• Подарочные сертификаты
• Начало работы и авторизация
• Обзор Lamoda Seller Partner API