Распространенные способы использования API Upcart

Как работает паттерн API

Большинство скриптов API Upcart следуют одному и тому же простому паттерну: Слушать событие корзины → Проверить условие → Выполнить действие Например: «Когда корзина загружается → проверить, пуста ли она → скрыть закрепленную кнопку». 💡 Впервые работаете с API? Начните со статьи Что такое API?, прежде чем переходить к примерам ниже.

Куда добавлять ваши скрипты

Все скрипты ниже размещаются в: Cart Editor → Settings → Custom HTML → Scripts (before load) Оберните каждый сниппет в теги <script>...</script> и сохраните. Для тестирования откройте консоль Dev Tools вашего браузера (F12) и ищите сообщения console.log.

Замечание об устаревших и современных колбэках

В Upcart есть два способа слушать события корзины:

Стиль	Пример	Статус
Современный (рекомендуется)	`upcartSubscribeAddedToCart(fn)`	Актуальный
Устаревший (deprecated)	`upcartOnAddToCart = fn`	Всё еще работает, выводит предупреждение в консоль

Все примеры ниже используют современный API. Существующие скрипты в старом стиле продолжат работать.

Пример 1: скрыть кнопку закрепленной корзины, когда корзина пуста

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

Как это работает: upcartSubscribeCartLoaded срабатывает при каждой загрузке корзины. Колбэк получает event с объектом cart, содержащим массив items. Мы суммируем quantity каждого товара, чтобы определить, пуста ли корзина. ⚠️ ВАЖНО: у event.cart НЕТ свойства item_count. Вы должны вычислить итог, перебирая event.cart.items.

Пример 2: логирование добавления товара в корзину

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

Свойства, доступные в event.item:

Свойство	Описание
`event.item.title`	Название товара
`event.item.quantityAdded`	Количество единиц, добавленных в этом действии
`event.item.quantity`	Общее количество этого товара в корзине сейчас
`event.item.variantId`	ID варианта Shopify
`event.item.handle`	Handle товара
`event.item.productId`	ID товара Shopify
`event.item.finalPrice`	Итоговая цена после скидок
`event.item.image`	URL изображения товара

Пример 3: интеграция со сторонним аналитическим приложением (например, TripleWhale)

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

Примечание: каждое стороннее приложение отличается. Уточните правильный формат события у команды поддержки вашего приложения.

Пример 4: автоматическое открытие корзины после добавления товара

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

Примечание: если опция «Open cart drawer on add to cart» уже включена в Cart Editor → Settings → Cart settings, этот скрипт вам не нужен.

Функция	Когда срабатывает	Что получает колбэк
`upcartSubscribeCartLoaded(fn)`	Данные корзины загружаются	`{ cart }` — у cart есть `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Товар добавлен в корзину	`{ item }` — у item есть `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	Cart drawer открывается	`{}` (пустой объект)
`upcartSubscribeCartClosed(fn)`	Cart drawer закрывается	`{}` (пустой объект)
`upcartSubscribeCartUpdated(fn)`	Содержимое корзины меняется	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Товар удален	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Нажата кнопка оформления заказа	`{ event }` — MouseEvent браузера
`upcartSubscribeUpsellsAddedToCart(fn)`	Добавлен товар апселла	`{ variant }` — имеет `.id` и `.title`
`upcartSubscribeUpsellsRendered(fn)`	Апселлы отображаются в корзине	`{ item, element }` — item — товар, element — DOM-узел
`upcartSubscribeNotesTextChanged(fn)`	Примечания корзины обновлены	`{ newNotesText, oldNotesText }` — новая строка примечаний и предыдущая
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	Меняется статус этапа вознаграждений	`{ numOfMilestonesCompleted, status }` — `status` может быть `"promotion"`, `"demotion"` или `"initial-state"`

Функции прямых действий

Функция	Что делает
`window.upcartOpenCart()`	Открывает cart drawer
`window.upcartCloseCart()`	Закрывает cart drawer
`window.upcartRefreshCart()`	Обновляет данные корзины
`window.upcartGetCart()`	Возвращает текущий объект корзины
`window.upcartRegisterAddToCart()`	Регистрирует добавление в корзину для конструкторов страниц (Replo, PageFly и т. д.)
`window.upcartFormatMoney()`	Форматирует цену в денежном формате вашего магазина

Полную документацию API см. в документации Upcart Public API.

Устранение неполадок

Скрипт не выполняется? Перепроверьте размещение: он должен находиться в Scripts (before load), а не after load.
Элемент не найден? Убедитесь, что селектор (например, #upCartStickyButton) соответствует фактическому ID элемента в вашей корзине.
Что-то сломалось? Закомментируйте свой скрипт, добавив // в начало каждой строки, сохраните и обновите страницу.
Все еще не получается? Дополнительные шаги по устранению неполадок см. в FAQ по API.

Начало работы

Модули корзины

Настройки корзины

Закреплённая кнопка корзины

Multicart

Кастомизации

Аналитика

Интеграции и совместимость

Оплата и аккаунт

Устранение неполадок

Распространенные способы использования API Upcart

Как работает паттерн API

Куда добавлять ваши скрипты

Замечание об устаревших и современных колбэках

Пример 1: скрыть кнопку закрепленной корзины, когда корзина пуста

Пример 2: логирование добавления товара в корзину

Пример 3: интеграция со сторонним аналитическим приложением (например, TripleWhale)

Пример 4: автоматическое открытие корзины после добавления товара

Функции прямых действий

Устранение неполадок

​Как работает паттерн API

​Куда добавлять ваши скрипты

​Замечание об устаревших и современных колбэках

​Пример 1: скрыть кнопку закрепленной корзины, когда корзина пуста

​Пример 2: логирование добавления товара в корзину

​Пример 3: интеграция со сторонним аналитическим приложением (например, TripleWhale)

​Пример 4: автоматическое открытие корзины после добавления товара

​Краткий справочник: функции подписки (современный API)

​Функции прямых действий

​Устранение неполадок

Как работает паттерн API

Куда добавлять ваши скрипты

Замечание об устаревших и современных колбэках

Пример 1: скрыть кнопку закрепленной корзины, когда корзина пуста

Пример 2: логирование добавления товара в корзину

Пример 3: интеграция со сторонним аналитическим приложением (например, TripleWhale)

Пример 4: автоматическое открытие корзины после добавления товара

Краткий справочник: функции подписки (современный API)

Функции прямых действий

Устранение неполадок