По всей базе знаний
Softline Checkout
Наверх
По всей базе знаний
Softline CheckoutИнтеграцияSubscriptions API
[GET] Получение данных подписки

[GET] Получение данных подписки (AR, PMR)

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

GET /v1/subscription/[suscription id]

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

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

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

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

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

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

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

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

https://api.ecommerce.softline.com/v1/subscription/111111_22222

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

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

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

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

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

id
string
required
Идентификатор подписки, данные которой содержатся в ответе.
type
string
required
Тип подписки

Варианты значений:
  • AR - подписка с автоматическим продлением (включая AR Trial)
  • PMR - подписка с продлением вручную
См. подробнее о типах подписок.
status
string
required
Статус подписки

Варианты значений:
  • active - подписка действует и не требует оплаты
  • not paid - подписка ожидает оплаты
  • cancelled - продление отменено
См. подробнее о статусах подписки с автоматическим продлением.
Для подписок с продлением вручную (PMR) используются аналогичные статусы, но не доступно восстановление подписки.
initial_order
object
required
Данные заказа, продукт которого является инициатором подписки (родительский заказ).
initial_order
/
order_id
number
required
Идентификатор родительского заказа
initial_order
/
create_date
string
required
Дата и время успешной оплаты родительского заказа.

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
url
string
required*
Ссылка на управление подпиской с автоматическим продлением (AR, AR Trial)
Ведет на якорь секции подписки на странице заказа-инициатора подписки.

* - Обязательное, если type равно AR. В ином случае параметр не передается.
period
string
required
Срок действия продукта в действующем периоде подписки
Это срок действия продукта из последнего оплаченного заказа, созданного в рамках подписки. Обратите внимание, этот срок относится к подписке в целом.

Например:
  • Была создана подписка на продукт со сроком действия 7 дней:
    • В ответе на запрос будет передано period = P7D
  • Произошло создание дочернего заказа на продукт со сроком действия 1 месяц:
    • В ответе на запрос будет передано period = P7D. Так как дочерний заказ еще не был оплачен и подписка еще не продлена, то передается срок из действующего периода подписки
  • Произошла оплата дочернего заказа:
    • В ответе на запрос будет передано передано period = P1M, так как дочерний заказ был оплачен, подписка продлена и действующий период подписки обновился
Формат параметра:
  • Формат: ISO 8601 code: P[число][ед.измерения]
  • Поддерживаемые единицы измерения: Y - год, M - месяц, D - день. Например, "P1Y" соответствует сроку "1 год"
expiration_date
string
required
Дата окончания периода действия подписки
Узнайте подробнее о том, как определяется эта дата.

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
next_charge_date
string
required*
Дата автоматической оплаты продления (AR, AR Trial)
Это дата следующего платежа. Узнайте подробнее о том, как определяется эта дата.
  • * - Обязательное, если type равно AR. В ином случае параметр не передается.
  • Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
next_notification_date
string
required
Дата напоминания о продлении
Это дата, когда покупателю будет отправлен email о предстоящем списании оплаты продления. Совпадает с датой, когда будет создан следующий дочерний заказ. Узнайте подробнее о том, как определяется эта дата.

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.

Обратите внимание. Если дата наступила, но заказ на продление не был создан по какой-либо причине, то каждый последующий день будет выполняться еще одна попытка создания - в сумме 6 попыток. При этом дата, передаваемая в этом параметре, не будет изменяться при повторных попытках.
currency
string
required
Код валюты стоимости продления
Совпадает с кодом валюты заказа на продукт инициатор-подписки. Валюта не может быть изменена в процессе жизни подписки.
  • Формат: ISO 4217 alpha-3, 3 символа.
  • Варианты значений см. в справочнике.
current_price
string
required
Стоимость подписки в текущем периоде действия
Это та сумма, которую оплатил покупатель (учитывает количество, VAT, скидку). Если текущий период действия завершен, и продление еще не оплачено, то здесь будет передана стоимость подписки в последнем оплаченном периоде действия.

Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка.
next_billing_price
string
required
Стоимость продления подписки в следующем периоде действия
Это та сумма, которую должен заплатить покупатель за продление (учитывает количество, VAT, скидки).

Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка.
next_product_name
string
required
Название продукта продления в следующем периоде действия подписки.

Пример положительного ответа для AR подписки

{
 "id": "111111_22222",
 "type": "AR",
 "status": "active",
 "initial_order": {
  "order_id": 111111,
  "create_date": "2021-08-13T09:16:35+03:00"
 },
 "url": "https://demo.checkout.softline.com/order/status/111111/fb61abcba997a5da0a627535a5879ab5#autorenewal",
 "period": "P1Y",
 "expiration_date": "2022-08-13T23:59:00+03:00",
 "next_charge_date": "2022-08-05T09:25:00+03:00",
 "next_notification_date": "2022-08-01T09:25:00+03:00",
 "currency": "USD",
 "current_price": "99.99",
 "next_billing_price": "80.00",
 "next_product_name": "Product renewal for 1 year"
}

Пример положительного ответа для PMR подписки

{
 "id": "111111_22222",
 "type": "PMR",
 "status": "active",
 "initial_order": {
  "order_id": 111111,
  "create_date": "2021-08-13T09:16:35+03:00"
 },
 "period": "P1Y",
 "expiration_date": "2022-08-13T23:59:00+03:00",
 "next_notification_date": "2022-08-01T09:25:00+03:00",
 "currency": "USD",
 "current_price": "99.99",
 "next_billing_price": "80.00",
 "next_product_name": "Product renewal for 1 year"
}

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

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

Справочник 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 Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
7000 No access to subscription management. Please contact technical support. Не получилось определить настройки подключения. Пожалуйста, обратитесь в службу поддержки.
7010 Invalid field value: [наименование поля] Запрос не валиден, например, не идентификатор подписки имеет неверный формат.
В том числе ошибка будет возвращена, если в поле передано null, и этот вариант значения не указан как допустимый в описании поля.

Справочник дополнительных кодов ошибок для 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": 7010,
   "message": "Subscription not found: 111111_22222"
  }
 ]
}
Политика конфиденциальности
© 2024 Softline