Share via

Изменение состояния выставления счетов за подписку для пользователя

  • Статья

Использование этого метода в API покупок Microsoft Store для изменения состояния выставления счетов надстройки с подпиской для конкретного пользователя. Можно отменить, расширить, компенсировать или отключить автоматическое возобновление для подписки.

Примечание

Этот метод может использоваться только учетными записями разработчиков, которые были выделены корпорацией Майкрософт для создания надстроек с подпиской для приложений универсальной платформы Windows (UWP). Надстройки подписки недоступны в настоящее время большинству учетных записей разработчика.

Библиотека Microsoft.StoreServices предоставляет функциональные возможности этого метода с помощью API StoreServicesClient.RecurrenceChangeAysnc.

Предварительные требования

Для использования этого метода вам понадобится:

  • Маркер доступа Azure AD, имеющий значение URI аудитории https://onestore.microsoft.com.
  • Ключ идентификатора Microsoft Store, который представляет идентификатор пользователя, имеющего разрешение на подписку, которую вы хотите изменить.

Дополнительные сведения см. в разделе Управление правами на продукты из службы.

Запрос

Синтаксис запроса

Метод Универсальный код ресурса (URI) запроса
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

Заголовок запроса

Заголовок Тип Описание
Авторизация строка Обязательный. Маркер доступа Azure AD в видемаркера>носителя<.
Узел строка Должен иметь значение purchase.mp.microsoft.com.
Content-Length number Длина текста запроса.
Content-Type строка Указывает тип запросов и ответов. На данный момент единственным поддерживаемым значением является application/json.

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

Имя Тип Описание Обязательно
recurrenceId строка Идентификатор подписки, которую необходимо изменить. Чтобы получить этот идентификатор, вызовите метод get subscriptions для пользовательского метода, определите запись текста ответа, представляющую надстройку подписки, которую вы хотите изменить, и используйте значение поля id для записи. Да

Текст запроса

Поле Тип Описание Обязательно
b2bKey строка Ключ идентификатора Microsoft Store, представляющий идентификатор пользователя, подписку которого требуется изменить. Да
changeType строка Одна из следующих строк, которая определяет тип вносимого изменения:
  • Cancel: отменяет подписку.
  • Extend: расширяет подписку. Если задать это значение, необходимо также включить параметр extensionTimeInDays.
  • Refund: возмещение клиенту денег за подписку.
  • ToggleAutoRenew: отключение автоматического продления подписки. Если автоматическое обновление в настоящее время отключено для подписки, это значение ни на что не влияет.
 Да
extensionTimeInDays строка Если параметр changeType имеет значение Extend, он указывает количество дней для расширения подписки. Да, если changeType имеет значение Extend, в противном случае нет.

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

В следующем примере показано, как использовать этот метод, чтобы расширить период подписки на 5 дней. Замените значение b2bKeyключом идентификатора Microsoft Store, представляющим идентификатор пользователя, подписку которого вы хотите изменить.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

Ответ

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

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Текст ответа

Текст ответа содержит следующие данные.

Значение Тип Описание
autoRenew Логическое Указывает, настроено ли в подписке автоматическое продление в конце текущего периода.
beneficiary строка Идентификатор бенефициара права, связанного с этой подпиской.
expirationTime; строка Дата и время завершения подписки в формате ISO 8601. Это поле доступно только при определенных состояниях подписки. Время окончания срока действия обычно означает окончание срока действия текущего состояния. Например, для активной подписки дата окончания срока действия указывает, когда произойдет следующее автоматическое продление.
expirationTimeWithGrace строка Дата и время истечения срока действия подписки, включая льготный период, в формате ISO 8601. Это значение указывает, когда пользователь потеряет доступ к подписке после сбоя автоматического продления подписки.
идентификатор строка Идентификатор подписки. Используйте это значение для подписки, которую вы хотите изменить при вызове метода изменение состояния выставления счетов подписки для пользователя.
isTrial Логическое Указывает, является ли подписка пробной версией.
lastModified строка Дата и время последнего изменения подписки в формате ISO 8601.
market строка Код страны (в двухбуквенном формате ISO 3166-1 alpha-2), в которой пользователь приобрел подписку.
productId строка Код продукта в Store для продукта, который представляет надстройку подписки в каталоге Microsoft Store. Пример кода продукта в Магазине: 9NBLGGH42CFD.
skuId строка Код продукта в Store для номера SKU, который представляет надстройку подписки в каталоге Microsoft Store. Пример кода продукта в Магазине для номера SKU: 0010.
startTime строка Дата и время начала для подписки в формате ISO 8601.
recurrenceState строка Принимает одно из следующих значений:
  • Нет. Указывает на бессрочную подписку.
  • Активный: подписка активна, и пользователь имеет право пользоваться службами.
  • Неактивен: срок действия подписки истек, и пользователь отключил параметр автоматического продления подписки.
  • Отменено: подписка была намеренно прекращена до истечения срока действия с возвратом денежных средств или без нее.
  • InDunning: подписка находится в режиме dunning (то есть срок действия подписки приближается, и корпорация Майкрософт пытается получить средства для автоматического продления подписки).
  • Сбой: период перехода закончился, и подписка не была продлена после нескольких попыток.

Примечание.

  • Неактивные/Отменен/Сбой — это состояния терминала. Когда подписка переходит в одно из этих состояний, пользователь должен повторно приобрести подписку, чтобы активировать ее снова. Пользователь не имеет права работать со службами в этих состояниях.
  • Если состояние подписки Canceled, значение expirationTime будет обновлено с указанием даты и времени отмены.
  • Идентификатор подписки будет оставаться неизменным в течение всего времени существования. Он не меняется при включении или выключении автоматического обновления. Если пользователь повторно приобретет подписку после достижения состояния окончания, будет создан новый идентификатор подписки.
  • Идентификатор подписки следует использовать для выполнения любой операции с отдельной подпиской.
  • Когда пользователь повторно приобретет подписку после ее отмены или завершения, на запрос по такому пользователю будут возвращены две записи: одна с идентификатором старой подписки в состоянии окончания, а другая — с идентификатором новой подписки в активном состоянии.
  • Всегда рекомендуется проверять recurrenceState и expirationTime, так как обновления recurrenceState могут быть отложены на несколько минут (а иногда на несколько часов).
cancellationDate строка Дата и время отмены подписки пользователя в формате ISO 8601.