Softline CheckoutИнтеграцияSubscriptions API

[POST] Изменение даты окончания действия подписки

[POST] Изменение даты окончания действия подписки (AR/PMR)

Описание запроса

POST /v1/subscription/modify_expiration_date

Запрос позволяет изменить дату окончания текущего периода действия подписки (AR/PMR). Обратите внимание, запрос влияет только на одну определенную подписку покупателя. Данные о сроке действия продукта не изменяются.

После изменения система автоматически пересчитает остальные связанные даты предстоящих событий для подписки (дату напоминания о продлении / создания дочернего заказа, дату оплаты продления и т.п.).

Узнайте подробнее:

Как рассчитываются даты для AR подписок и происходит их пересчет при сдвиге.
Как рассчитываются даты для PMR подписок. Принцип расчета сдвига такой же как для AR, но сроки расчета относительно даты окончания периода действия подписки отличаются.

Обратитесь в службу поддержки, если вам нужна помощь с пересчетом дат.

Вы можете изменить дату, если:

Подписка имеет статус active. В ином случае, если создан заказ на продление, и он ожидает оплаты (подписка имеет статус not_paid) или подписка отменена (подписка имеет статус cancelled), изменить дату окончания текущего периода действия подписки нельзя. Вы можете узнать текущий статус подписки с помощью запроса на получение данных подписки.
Если вы хотите уменьшить дату окончания, то новая дата соответствует ограничениям. Это нужно, чтобы после пересчета других дат у подписки хватало времени создать заказ на продление.

Если вы хотите сдвинуть дату, чтобы протестировать работу подписок, то вы можете обратиться в службу поддержки, чтобы моментально инициировать создание и оплату заказа на продление.

Данные для отправки запроса

Endpoint URL:
- Боевая среда: https://api.ecommerce.softline.com/v1/subscription/modify_expiration_date
- Тестовая среда: https://api.ecommerce.softline.com.demoslweb.com/v1/subscription/modify_expiration_date
Метод: POST
Формат: JSON
Авторизация: с помощью токена

Параметры заголовка

content-type

string

required

MIME-тип данных в теле запроса.
Должен быть равен "application/json".

AuthorizationJWT

required

Авторизационный токен.

Формат значения: Bearer [token]
Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API.

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

required

Идентификатор подписки
Формат: NN_MM, где NN это идентификатор заказа, который инициировал подписку (родительский заказ).
Вы можете получить его из:

Webhook-оповещения (subscription.id)
Из ответа на запрос к Orders API

expiration_date

string

required

Новая дата окончания периода действия подписки.

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
Если вы хотите уменьшить период действия подписки, то новая дата окончания должна быть такой, чтобы расчетная дата напоминания о продлении попадала, как минимум, на следующий день после выполнения запроса. В ином случае заказ на продление не получится создать.
Узнайте подробнее:
- Как рассчитывается дата напоминания о продлении для AR подписок
- Как рассчитывается дата напоминания о продлении для PMR подписок

Для AR подписок при сроках по умолчанию, новая дата окончания периода действия подписки должна отвечать условию:

Если срок действия продукта < 6 месяцев, то дата окончания периода должна быть больше даты отправки запроса на 5 дней (или более).
Например, если запрос отправлен 1 января, то дата окончания периода должна быть равна 6 января или более поздней дате.
Если срок действия продукта ≥ 6 месяцев, то дата окончания периода должна быть больше даты отправки запроса на 26 дней (или более).
Например, если запрос отправлен 1 января, то дата окончания периода должна быть равна 27 января или более поздней дате.

Если вы хотите сдвинуть дату, чтобы протестировать создание заказа на продление, то вы можете обратиться в службу поддержки, чтобы инициировать создание моментально.

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

{
 "id": "111111_22222",
 "expiration_date": "2022-08-13T09:16:35+03:00"
}

Ответ на запрос

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

Положительный ответ

При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK.

Ответ об ошибке

В случае ошибки при обработке запроса вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.

Справочник HTTP-кодов ответа сервера при ошибке

Код ответа сервера	Описание
HTTP/1.1 400 Bad Request	Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.). В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 401 Unauthorized	Неуспешная аутентификация. В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 404 Not found	Неверный URL запроса или подписка не найдена. Проверьте адрес запроса. В теле ответа может быть передан дополнительный код ошибки (один или несколько).
HTTP/1.1 500 Request Error	Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки.

Справочник дополнительных кодов ошибок для HTTP 400

Error	Message	Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
110	JSON is not valid.	Запрос не может быть выполнен. Структура полей запроса не валидна. Проверьте поля в теле запроса на соответствие формату JSON.
111	Invalid data format (Content-type).	Запрос не может быть выполнен. Неправильный заголовок запроса. Content-type должен быть равен application/json.
7000	No access to subscription management. Please contact technical support.	Запрос не может быть выполнен. Не получилось определить настройки подключения. Пожалуйста, обратитесь в службу поддержки.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
7010	Invalid field value: [наименование параметра].	Запрос не может быть выполнен. Запрос не валиден, например, не идентификатор подписки имеет неверный формат. В том числе ошибка будет возвращена, если в поле передано null, и этот вариант значения не указан как допустимый в описании поля.
7110	Impossible to change the subscription expiration date. The subscription status is not_paid (payment pending).	Дата окончания действия подписки не может быть изменена, так как уже был создан заказ на продление, и подписка имеет статус not_paid.
7120	Impossible to change the subscription expiration date. The subscription status is cancelled (cancelled).	Дата окончания действия подписки не может быть изменена, так как подписка была отменена и имеет статус cancelled.
7130	Impossible to change the subscription expiration date. No renewal order can be created for a new subscription expiration date.	Дата окончания действия подписки не может быть изменена, переданная дата (expiration_date) не отвечает ограничениям.
7900	Failed to execute the action with the subscription. Please contact Technical Support.	Действие с подпиской недоступно по техническим причинам на нашей стороне. Пожалуйста, повторите запрос позднее или обратитесь в службу поддержки.

Справочник дополнительных кодов ошибок для HTTP 401

Справочник этих ошибок одинаковый для всех API, которые используют авторизацию по токену.

Справочник дополнительныхкодов ошибок для HTTP 404

Error	Message	Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
7400	Subscription not found.	Запрос не может быть выполнен. Подписка с переданным идентификатором не найдена, или у вас нет прав на получение ее данных.

Параметры в теле ответа

errors

array [objects]

required

Список ошибок.

errors / [error object]

error

number

required

Код ошибки.

errors / [error object]

message

string

required

Описание ошибки.

Пример ответа об ошибке

{
 "errors": [{
   "error": 7110,
   "message": "Impossible to change the subscription expiration date. The subscription status is not_paid (payment pending)."
  }, {
   "error": 7130,
   "message": "Impossible to change the subscription expiration date. No renewal order can be created for a new subscription expiration date."
  }
 ]
}