Изменение условий подписки

POST/integration/subscriptions/{uuid}/update

Обновление условий не списывает деньги

Метод не создаёт платёж и не подтверждает оплату периода. Новые условия применяются к последующим списаниям. Для отдельной попытки есть charge-now, для триала есть пошаговый пример.

Когда можно изменить условия

Подписка принадлежит вашему мерчанту, находится в active или past_due, а привязка и финансовые параметры подтверждены. Мерчант должен быть включён, его баланс не должен быть заморожен. Провайдер может запретить изменение при запрошенной отмене или незавершённом списании. Пока предыдущая операция не разрешена, новую запускать нельзя.

Обязательные заголовки

Поле	Тип	Описание
`X-Api-Key`обязательное	`string`	API-ключ владельца подписки. Запрос выполняется с вашего сервера
`Content-Type`обязательное	`string`	`application/json`
`Idempotency-Key`обязательное	`string`	Непустой ключ до 200 символов, без управляющих символов. Сохраните его вместе с исходным JSON до отправки запроса

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

Поле	Тип	Описание
`amount`	`integer`	Новая базовая сумма одного списания в копейках, больше нуля. Например, `29000` означает 290 ₽. JSON-строки, null и дробные копейки не принимаются
`next_charge_at`	`string (ISO 8601)`	Ближайшее списание с часовым поясом. Например, `2026-11-06T09:00:00Z`. Для новой операции дата не в прошлом; дробная часть секунды не более 6 знаков
`interval`	`string`	`daily`, `weekly`, `monthly` или `yearly`. Только вместе с `interval_count`
`interval_count`	`integer`	Количество единиц периода. Для daily: 1–31; weekly: 1–4; monthly: 1–12; yearly: 1–3. Только вместе с `interval`

Передайте хотя бы один параметр. Не переданные поля сохраняются; null не очищает настройку. Сумма не умножается на interval_count. Общий числовой предел суммы в API: 9007199254740991 копейка; фактический допустимый размер ограничивается настройками метода, комиссией и холдом.

Передано	Результат
Только amount	Меняется цена, дата и период остаются прежними
Только next_charge_at	Переносится ближайшее списание, период не меняется
interval и interval_count	Меняется период, ближайшая дата автоматически не пересчитывается
Все поля	Меняются цена, ближайшая дата и период одним запросом

Пример изменения цены и расписания

Пример отправляется до 6 ноября 2026 года, 09:00 UTC. Для реального запроса вычислите будущую дату на вашем сервере. Z означает UTC;09:00:00Z и 12:00:00+03:00 обозначают один момент.

200 OK

curl -X POST 'https://api.cashera.cash/api/v1/integration/subscriptions/31dc7faa-c380-4ec7-a258-3202a2211e76/update' \
  -H "X-Api-Key: $CASHERA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: subscription-pro-10428-upgrade-v1' \
  -d '{
    "amount": 29000,
    "next_charge_at": "2026-11-06T09:00:00Z",
    "interval": "monthly",
    "interval_count": 1
  }'

Ответ является объектом подписки без обёртки data. В примере комиссию 5% оплачивает мерчант, дополнительной комиссии плательщика нет. Реальные gross_amount, net_amount и fee_amountберите из ответа: они зависят от сохранённых условий и фактической комиссии. Новые условия подтверждаются у провайдера до успешного ответа Cashera. Изменение цены не пересчитывает уже созданные платежи.

Примеры частичного изменения

Каждый пример является самостоятельной новой операцией и требует своего ключа. При повторе уже начатой операции её JSON менять нельзя.

{
  "amount": 29999
}

Повторы и ошибки

Ключ привязан к одной подписке, действию и исходным параметрам. Повтор с тем же ключом продолжает исходную операцию; повтор завершённого update не применяет его заново. Он возвращает текущее локальное состояние подписки, которое после других изменений может отличаться от первого ответа. Тот же ключ с другим JSON или для charge-now вызывает 409.

5xx или таймаут не доказывают, что изменение не применилось

Провайдер мог принять новые параметры, пока ответ или их проверка были недоступны. Сохраните исходный ключ и параметры. Повторяйте ту же операцию с паузой; не посылайте другую цену или новый ключ для обхода 409. Восстановление также выполняется фоновыми задачами Cashera.

422 означает ошибку параметров или финансовых ограничений,400 может означать запрет провайдера, 409 также возникает при неподходящем статусе или другой незавершённой операции. Полный порядок действий приведён в разделе ошибок и безопасных повторов.