Заказы и подписки

Тело запроса

• products (array, обязательно) — позиции корзины;
• products[].id (integer, обязательно) — ID товара;
• products[].quantity (integer, обязательно) — количество, от 1;
• promo_code (string, опционально) — латинские буквы, цифры и дефис, до 64 символов.

{
    "products": [
        {
            "id": 28504,
            "quantity": 3
        }
    ],
    "promo_code": "WELCOME-10"
}

Ответ

{
    "price": 1952.4,
    "discount": 195.24,
    "total": 1657.16,
    "quantity_pack": 3,
    "original_price": 1952.4,
    "product_discount_amount": 195.24,
    "promo_discount_amount": 100,
    "total_discount_amount": 295.24,
    "final_price": 1657.16,
    "applied_discount": {
        "id": 7,
        "code": "WELCOME-10",
        "name": "Приветственная скидка",
        "type": "fixed",
        "value": 100
    },
    "discount_error": null,
    "products": [
        {
            "id": 28504,
            "price": 650.8,
            "quantity": 3,
            "pieces_per_pack": 1,
            "quantity_pack": 3,
            "wholesale": false
        }
    ]
}

price, discount и total сохранены для совместимости. Для нового интерфейса используйте явные поля original_price, product_discount_amount, promo_discount_amount, total_discount_amount и final_price.

Неприменимый промокод не ломает расчёт: backend возвращает цены без промо-скидки и объект discount_error. Ошибка товара или остатка возвращается как 422.

Тело запроса

• delivery_type_id (integer, обязательно) — способ доставки;
• delivery_subtype_id (integer, условно обязательно) — требуется при delivery_type_id = 2;
• delivery_subtype_param_id (integer, условно обязательно) — требуется при delivery_subtype_id = 1;
• shop_id (integer, условно обязательно) — требуется при delivery_type_id = 1;
• address (string, условно обязательно) — требуется при delivery_subtype_id = 2;
• payment_type_id (integer, опционально) — способ оплаты;
• payment_method_type (string, опционально) — допустимый тип способа онлайн-оплаты;
• promo_code (string, опционально) — промокод;
• products (array, обязательно) — позиции корзины;
• products[].id (integer, обязательно) — ID товара;
• products[].quantity (integer, обязательно) — количество, от 1.

Всегда получайте ID доставки, оплаты и магазина из справочников витрины. Не переносите ID из примера в production-конфигурацию.

{
    "delivery_type_id": 2,
    "delivery_subtype_id": 2,
    "payment_type_id": 2,
    "address": "115477, г Москва, ул Деловая, д 20",
    "promo_code": "WELCOME-10",
    "products": [
        {
            "id": 28504,
            "quantity": 3
        }
    ]
}

Ответ

{
    "order": {
        "id": 169,
        "status": {
            "id": 1,
            "name": "Ожидает оплаты"
        },
        "price": "1657.16",
        "promo_code": "WELCOME-10",
        "original_price": 1952.4,
        "product_discount_amount": 195.24,
        "promo_discount_amount": 100,
        "total_discount_amount": 295.24,
        "final_price": 1657.16,
        "delivery_type": {},
        "delivery_subtype": {},
        "delivery_subtype_param": null,
        "payment_type": {},
        "yookassa_payment_method_type": null,
        "address": "115477, г Москва, ул Деловая, д 20",
        "shop": null,
        "products": [],
        "payment_link": "https://yoomoney.ru/checkout/...",
        "created_at": "2026-08-16T10:00:00+00:00",
        "redeem_token": null,
        "redeemed_count": 0,
        "total_tickets": 0,
        "last_redeemed_at": null
    }
}

Для карточной оплаты backend создаёт платёж после фиксации заказа. Если платёж создать не удалось, заказ отменяется и API возвращает 502. Ошибки цены, промокода, доставки или остатка возвращаются как 422.

Возвращает только заказы текущего клиента в текущем Application.

Ответ

{
    "orders": [
        {
            "id": 169,
            "status": {
                "id": 1,
                "name": "Ожидает оплаты"
            },
            "final_price": 1657.16,
            "payment_link": "https://yoomoney.ru/checkout/...",
            "created_at": "2026-08-16T10:00:00+00:00"
        }
    ],
    "ordersCount": 1
}

Backend проверяет и владельца, и Application. Чужой заказ или заказ другого приложения возвращается как 404, чтобы не раскрывать его существование.

Для билетов и пропусков ответ может содержать redeem_token, redeemed_count, total_tickets и last_redeemed_at. Эти поля возвращаются только владельцу заказа.

Ответ

{
    "order": {
        "id": 169,
        "status": {
            "id": 1,
            "name": "Ожидает оплаты"
        },
        "final_price": 1657.16,
        "payment_link": "https://yoomoney.ru/checkout/...",
        "redeem_token": null,
        "redeemed_count": 0,
        "total_tickets": 0,
        "last_redeemed_at": null
    }
}

Ошибки

• 401 — один из токенов отсутствует или недействителен;
• 404 — заказа нет, он принадлежит другому клиенту либо другому Application.

Этот endpoint создаёт клиента и заказ без предварительного входа. Используйте его только для простой контактной формы, а не как основной checkout: runtime фиксирует курьерскую доставку и не поддерживает полный набор условий обычного заказа.

Параметры запроса

• first_name (string, обязательно) — имя клиента;
• last_name (string, обязательно) — фамилия клиента;
• middle_name (string|null, опционально) — отчество;
• phone (string, обязательно) — телефон клиента;
• address (string, обязательно) — адрес;
• payment_type_id (integer, обязательно) — способ оплаты;
• products (array, обязательно) — позиции заказа;
• products[].id (integer, обязательно) — ID товара;
• products[].quantity (integer, обязательно) — количество.

Пример запроса

{
    "first_name": "Иван",
    "last_name": "Иванов",
    "middle_name": null,
    "phone": "79991234567",
    "address": "г Москва, ул Деловая, д 20",
    "payment_type_id": 2,
    "products": [
        {
            "id": 28504,
            "quantity": 1
        }
    ]
}

Ответ

API возвращает созданный объект order той же формы, что обычное создание заказа.

Запрос ограничен отдельными лимитами по IP и телефону. Для личного кабинета, истории и повторных покупок используйте обычный вход клиента.

Передайте ровно одно поле: nomenclature_id или nomenclature_ids.

Параметры запроса

• nomenclature_id (integer, условно обязательно) — один тариф;
• nomenclature_ids (integer[], условно обязательно) — от 1 до 20 уникальных ID тарифов;
• autopay_consent (boolean, обязательно) — должно быть true;
• payment_method_type (string, опционально) — допустимый тип оплаты.

Пример запроса

{
    "nomenclature_id": 34780,
    "autopay_consent": true
}

Ответ

Ответ для одного тарифа:

{
    "order_id": 501,
    "nomenclature_id": 34780,
    "amount": "490.00",
    "currency": "RUB",
    "billing_period_months": 1,
    "payment_method_type": "bank_card",
    "payment_link": "https://yoomoney.ru/checkout/..."
}

• 201 — создан новый checkout;
• 200 — возвращён уже существующий незавершённый checkout;
• 202 — результат создания платежа ещё уточняется. Не создавайте параллельный checkout: повторите запрос или получите состояние заказа.

Конфликт с другим незавершённым платежом возвращается как 409. Недоступный тариф, отсутствие платёжного склада или неверные условия — как 422.

Ответ

{
    "data": [
        {
            "id": 42,
            "application_id": 17,
            "plan_slug": "nomenclature-34780",
            "nomenclature_id": 34780,
            "billing_period_months": 1,
            "amount": "490.00",
            "currency": "RUB",
            "status": "active",
            "current_period_start": "2026-08-15T10:00:00+00:00",
            "current_period_end": "2026-09-15T10:00:00+00:00",
            "next_charge_at": "2026-09-15T10:00:00+00:00",
            "latest_payment": {
                "status": "succeeded"
            },
            "can_retry_payment": false,
            "retry_payment_reason": "already_paid"
        }
    ]
}

next_charge_at означает «не раньше этого времени»; фактическая попытка выполняется ближайшим запуском планировщика.

Используйте endpoint только когда у клиента уже есть активный saved_payment_method_id текущего Application.

Параметры запроса

• nomenclature_id (integer, условно обязательно) — ID тарифа;
• plan_slug (string, условно обязательно) — slug тарифа вместо nomenclature_id;
• saved_payment_method_id (integer, обязательно) — сохранённый способ оплаты;
• autopay_consent (boolean, обязательно) — должно быть true.

Пример запроса

{
    "nomenclature_id": 34780,
    "saved_payment_method_id": 9,
    "autopay_consent": true
}

Ответ

Успешно активированная подписка возвращается как 201; продолжающееся или требующее проверки списание — как 202. Ответ содержит объект data с подпиской. Окончательная ошибка первого списания возвращается как 422.

Параметры запроса

• nomenclature_id (integer, опционально) — новый тариф;
• plan_slug (string, опционально) — новый тариф по slug;
• saved_payment_method_id (integer, опционально) — уже сохранённый способ оплаты;
• autopay_consent (boolean, условно обязательно) — передайте true, если меняются тариф, цена, период или способ оплаты.

Пример запроса

{
    "nomenclature_id": 34786,
    "autopay_consent": true
}

Ответ

API возвращает объект data с обновлённой подпиской.

Не используйте этот endpoint для ввода новой карты. Он принимает только уже сохранённый способ оплаты того же платёжного контура.

Ответ

Отмена переводит подписку в canceled, записывает canceled_at и возвращает объект data с обновлённой подпиской. Повторная отмена или попытка отменить подписку во время актуального списания возвращается как 422.

Параметры запроса

• autopay_consent (boolean, обязательно) — должно быть true.

Пример запроса

{
    "autopay_consent": true
}

Ответ

API возвращает объект data с возобновлённой подпиской. Если оплаченный период истёк, подписка переходит в past_due; иначе — в active.

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

Параметры запроса

• per_page (integer, опционально) — от 1 до 100, по умолчанию 20.

Ответ

Возвращается стандартная paginated collection платежей только для подписки текущего клиента и Application.

Ответ

Повторить можно только последнюю финализированную неуспешную попытку, если условия подписки не изменились и предыдущий результат не требует сверки. Перед показом кнопки используйте can_retry_payment и retry_payment_reason из подписки.

409 означает, что платёж ещё обрабатывается или требует reconciliation; 422 — попытка не подходит для повтора.

Ответ

{
    "data": [
        {
            "id": 9,
            "payment_method_type": "bank_card",
            "card_type": "Visa",
            "card_last_4": "4242",
            "title": "Visa •••• 4242",
            "is_active": true,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ]
}

API возвращает только безопасное представление карты. Полный номер и CVC не сохраняются в этом контракте.

Ответ

{
    "message": "Способ оплаты отвязан"
}

Backend деактивирует способ оплаты только в контексте текущего клиента и Application. Если он нужен действующей подписке, операция может быть отклонена.

Параметры запроса

• autopay_consent (boolean, обязательно) — должно быть true.

Не передавайте card, card_number, cvc, payment_method_data или собственный return_url: validation специально запрещает эти поля.

Пример запроса

{
    "autopay_consent": true
}

Ответ

Backend создаёт provider-flow и возвращает его состояние:

{
    "id": 31,
    "subscription_id": 42,
    "status": "pending",
    "confirmation_url": "https://yoomoney.ru/confirmation/...",
    "saved_payment_method_id": null,
    "expires_at": "2026-08-16T11:00:00+00:00"
}

Откройте confirmation_url, затем синхронизируйте попытку.

Ответ

Возвращает тот же объект попытки. Завершённый статус содержит saved_payment_method_id; для незавершённого confirmation_url может оставаться доступным.