Цены

Цену через API магазин считает так же, как для покупателя на витрине. Отдельного прайса для API нет. Покупателем при этом считается контакт, которому владелец выдал ключ, поэтому дропшиппер или оптовик сразу видит свою цену.

Цену можно получить двумя способами:

• блоком price у каждого артикула в /products, /products/{id} и /skus, если у ключа есть право prices:read;
• отдельным лёгким списком /prices без описаний и фото. Ему нужно только право prices:read, право на каталог не требуется.

Как считается цена#

1. Магазин берёт цену артикула. Если владелец задал артикулу цену в другой валюте, магазин переводит её в основную валюту.
2. Применяет акции каталога, которые сейчас действуют на товар.
3. Применяет правила дополнений цен для вашего контакта, то есть цену для его категории покупателей и персональные цены. Так работает, например, дополнение «Оптовые цены». Если таких дополнений в магазине нет, цена одна для всех. Если у вашего контакта есть личный кабинет на сайте магазина, вы считаетесь зарегистрированным покупателем и получаете цены для зарегистрированных покупателей, а без кабинета — цены гостя.
4. Переводит итог в валюту витрины по текущему курсу магазина. Один курс действует на весь ответ.

Учтите несколько правил:

• Поле price — цена одной единицы продажи при покупке одной единицы. Цены от количества («от 10 штук дешевле») приходят отдельно, в списке tiers. Его поля описаны в разделе «Ступени по количеству».
• Если самая малая покупка товара меньше одной единицы, например 0,1 кг, и стоит она по другой цене, эта цена придёт первой ступенью в tiers.
• Скидки корзины, промокоды и бонусы магазин считает только при оформлении заказа, в цене API их нет.
• Налог уже входит в цену, как и на витрине.
• Закупочную цену API не отдаёт никогда.

По этим же правилам магазин считает цены в заказе, который вы передаёте через API. Цена позиции в заказе совпадает с price из /prices, а при большом количестве — с ценой подходящей ступени из tiers. Подробнее на странице «Заказы партнёра».

Валюта витрины приходит в поле currency. Цены другой витрины вы получите, передав её номер в storefront_id. Номера и валюты витрин отдаёт /storefronts.

Поля цены#

Эти поля одинаковы в блоке price у артикула и в записи списка /prices.

Пример блока у артикула:

"price": { "price": "208.32", "compare_price": "320.00", "discount_percent": 35, "currency": "UAH", "tiers": [] }

Тот же артикул на витрине в долларах при курсе 41,25:

"price": { "price": "5.05", "compare_price": "7.76", "discount_percent": 35, "currency": "USD", "tiers": [] }

Ступени по количеству#

Ступень задаёт цену одной единицы, если в заказе не меньше указанного количества этого артикула, например «от 10 штук по 180 ₴». Ступени задаёт дополнение цен, сейчас это «Оптовые цены» версии 1.4.0 и новее. Список tiers пустой, если такого дополнения в магазине нет или оно выключено, а также если у артикула нет ступеней для вашего контакта.

В список попадают общие ступени и ступени той категории покупателей, в которой состоит ваш контакт. Ступеней других категорий вы не увидите. Владелец задаёт ступень всему товару или отдельному артикулу. Ступень товара приходит у каждого его артикула, ступень артикула — только у него.

Цену ступени магазин считает так же, как в корзине при таком количестве. В ней уже учтены акции каталога и скидка вашей категории. Учтены и две настройки дополнения «Оптовые цены»: «Если на товар уже действует акция» и «Не продавать ниже закупочной цены». Скидок корзины, промокодов и бонусов в цене ступени нет, как и в price.

У товара, который продают только упаковками (pack_only: true), порог, который не делится на упаковку нацело, начинает действовать позже, чем указано в min_quantity. Корзина округляет количество такого товара вверх до целых упаковок. Поэтому цена ступени действует с первого целого числа упаковок, которое не меньше порога. Например, если порог 10 м², а упаковка 1,4 м², цена ступени действует с 8 упаковок, то есть с 11,2 м².

Правила списка:

• ступени отсортированы по min_quantity по возрастанию;
• на один порог приходит одна ступень с той ценой, которую вы получите при заказе такого количества. Если владелец задал одинаковый порог и товару, и его артикулу, действует ступень артикула;
• цена ступени действует от её порога до порога следующей ступени, сам этот порог уже не входит. Последняя ступень действует от своего порога на любое количество;
• ступень приходит, если её цена отличается от цены предыдущей ступени, а у первой ступени — от price. Цены сравниваются в валюте ответа, после округления до двух знаков. Ступень с той же ценой ничего не меняет, поэтому её нет в списке. Ступень дороже предыдущей приходит, потому что с её порога вы платите больше;
• если самая малая покупка товара меньше одной единицы, первой может прийти ступень с таким порогом. Её порог равен минимальному количеству товара. У товара, который продают только упаковками, минимальное количество округляется вверх до целого числа упаковок. Такая ступень приходит, только когда её цена отличается от price. Не позже порога в одну единицу в списке всегда есть ступень по цене price, поэтому цена самой малой покупки действует только на количество меньше одной единицы.

Пример: обычная цена 200 ₴, от 10 штук 180 ₴, от 50 штук минус 20 %.

"price": {
    "price": "200.00",
    "compare_price": null,
    "discount_percent": null,
    "currency": "UAH",
    "tiers": [
        { "min_quantity": "10.000", "min_packs": null, "price": "180.00", "discount_percent": 10 },
        { "min_quantity": "50.000", "min_packs": null, "price": "160.00", "discount_percent": 20 }
    ]
}

Верхняя ступень бывает дороже нижней. Например, обычная цена артикула 100 ₴. Владелец задал всему товару цену 80 ₴ от 10 штук, а этому артикулу — 100 ₴ от 50 штук. Тогда артикул от 10 до 49 штук стоит 80 ₴, а от 50 штук снова 100 ₴, и процента скидки у этой ступени нет:

"tiers": [
    { "min_quantity": "10.000", "min_packs": null, "price": "80.00", "discount_percent": 20 },
    { "min_quantity": "50.000", "min_packs": null, "price": "100.00", "discount_percent": null }
]

Весовой товар продают от 0,1 кг по 100 ₴ за килограмм, а от 1 кг — по 90 ₴. Цена одного килограмма уже оптовая, поэтому в price придёт 90 ₴. Чтобы было видно, что меньше килограмма стоит 100 ₴, первой придёт ступень с порогом 0,1. Вторая ступень возвращает цену 90 ₴ с одного килограмма. Процента скидки нет ни у одной из них, потому что ни одна не дешевле price:

"price": {
    "price": "90.00",
    "compare_price": "100.00",
    "discount_percent": 10,
    "currency": "UAH",
    "tiers": [
        { "min_quantity": "0.100", "min_packs": null, "price": "100.00", "discount_percent": null },
        { "min_quantity": "1.000", "min_packs": null, "price": "90.00", "discount_percent": null }
    ]
}

Когда владелец меняет ступень, магазин отмечает изменёнными все артикулы этого товара, и новые ступени придут через updated_since в /products и /skus. Правка скидки категории или настроек дополнения «Оптовые цены» отмечает изменённым весь каталог.

GET /api/v1/prices#

Цены артикулов опубликованных товаров. Право: prices:read. Порядок: по номеру артикула, по возрастанию. Адрес подходит, чтобы регулярно сверять цены, например раз в час.

Код и штрихкод ищутся так же, как в /products. Нужно совпадение целиком, а регистр букв не важен.

У /prices нет updated_since. Цена артикула меняется от его правки, от акции, нового курса, смены валюты витрины и правки в дополнении «Оптовые цены» версии 1.3.1 и новее, включая ступени. Такие изменения видны через updated_since в /skus. Другое дополнение цен может не сообщать магазину о своих правках, и тогда новые цены через updated_since не придут. Поэтому сверяйте /prices целиком, листая по after_id. Как часто это делать, описано в разделе «Изменения: updated_since». Если владелец включил вам сообщение «Могли измениться цены», магазин сам пришлёт номера артикулов, цены которых стоит перечитать. Как принимать такое сообщение, описано на странице «Сообщения партнёру (вебхуки)».

Когда ваш контакт переводят в другую категорию покупателей, меняются цены всего каталога. Об этом говорит поле settings_changed_at ответа GET /api/v1/me. Если оно позже вашей прошлой сверки, заберите цены заново.

Номера в sku_ids, которых нет или которые принадлежат неопубликованным товарам, магазин молча пропускает, а повторы считает один раз. Сверяйте ответ по полю sku_id.

curl "https://shop.example.ua/api/v1/prices?sku_ids=2108,2109" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "sku_id": 2108,
            "product_id": 1045,
            "sku": "730601",
            "price": "208.32",
            "compare_price": "320.00",
            "discount_percent": 35,
            "currency": "UAH",
            "tiers": []
        },
        {
            "sku_id": 2109,
            "product_id": 1045,
            "sku": "730602",
            "price": "250.00",
            "compare_price": null,
            "discount_percent": null,
            "currency": "UAH",
            "tiers": [
                { "min_quantity": "10.000", "min_packs": null, "price": "225.00", "discount_percent": 10 }
            ]
        }
    ],
    "meta": { "total": 2, "limit": 100, "offset": 0 },
    "links": { "next": null, "prev": null }
}

Полная сверка всех цен выглядит так:

url="https://shop.example.ua/api/v1/prices?after_id=0&limit=200"

while [ "$url" != "null" ]; do
    page=$(curl -s "$url" -H "Authorization: Bearer $CARTIX_KEY")
    echo "$page" | jq -c '.data[] | {sku_id, price, currency}'
    url=$(echo "$page" | jq -r '.links.next')
done