purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

이 엔드포인트는 사용자가 Microsoft Store를 통해 소유하는 구독 제품 유형의 상태를 쿼리하는 데 사용됩니다. 자동 갱신 청구에 실패한 경우 제품의 유예 기간을 포함하여 이러한 구독에 대한 컬렉션 서비스보다 더 많은 정보를 제공합니다.

사전 요건

이 API를 사용하려면 다음이 필요합니다.

• 대상 URI 값이 https://onestore.microsoft.com인 Microsoft Entra ID 액세스 토큰
• 무료 제품을 부여하려는 사용자 ID를 나타내는 사용자 구매 ID 키

자세한 내용은 서비스 간 인증을 위한 사용자 Store ID 요청을 참조하세요.

또한 서비스에 표시하려는 제품은 파트너 센터에서 추가 구성이 필요합니다.

제품을 올바르게 구성하는 방법은 사용자 Store ID/Microsoft Entra ID 인증이 있는 제품을 보고 관리하는 데 필요한 추가 구성을 참조하세요.

요청

요청 구문

요청 헤더

요청 본문

요청 예제

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

응답

응답 본문

RecurrenceItem 개체에는 다음 매개 변수가 포함됩니다.

되풀이 상태

• 비활성/취소됨/실패는 최종 상태입니다. 구독이 이러한 상태 중 하나가 되면 사용자는 구독을 다시 구매하여 다시 활성화해야 합니다. 사용자는 이러한 상태에서 서비스를 사용할 수 없습니다.
• 구독이 취소되면 만료 시간은 취소 날짜와 시간으로 업데이트됩니다.
• 구독의 ID는 전체 수명 동안 동일하게 유지됩니다. 자동 갱신 옵션이 켜져 있거나 꺼져 있어도 변경되지 않습니다. 사용자가 터미널 상태에 도달한 후 구독을 재구매하면 새 구독 ID가 생성됩니다.
• 구독 ID는 개별 구독에서 작업을 실행하는 데 사용해야 합니다.
• 사용자가 구독을 취소하거나 중단한 후 재구매할 때 사용자에 대한 결과를 쿼리하면 두 개의 항목이 표시됩니다. 하나는 터미널 상태의 이전 구독 ID이고 다른 하나는 활성 상태의 새 구독 ID입니다.
• recurrenceState 업데이트가 몇 분(때로는 몇 시간) 지연될 수 있으므로 항상 recurrenceState와 expirationTime을 모두 확인하는 것이 좋습니다.

응답 예제

HTTP/1.1 200 OK
date: Tue, 17 Aug 2021 21:22:28 GMT
content-type: application/json; charset=utf-8
content-length: 2382
ms-cv: aft4s000mwNmYF.0
x-content-type-options: nosniff
x-envoy-upstream-service-time: 2099

{
    "items": [
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-08-25T23:59:59.00+00:00",
            "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00",
            "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92",
            "isTrial": false,
            "lastModified": "2021-07-26T22:59:55.99+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Active"
        },
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T21:08:30.52+00:00",
            "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00",
            "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5",
            "isTrial": false,
            "lastModified": "2021-07-26T21:08:34.61+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-15T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T21:08:31.52+00:00"
        },
        {
            "autoRenew": false,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T22:35:29.54+00:00",
            "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00",
            "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde",
            "isTrial": false,
            "lastModified": "2021-07-26T22:35:33.96+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T22:35:30.54+00:00"
        },
    ]
}

예시 응답 설명

위의 예시에서 이 사용자는 이전에 취소된 두 개의 구독 기간과 2021년 7월 26일에 시작된 현재 활성 기간이 있습니다. 구독 기간의 종료 날짜는 2021년 8월 26일입니다. 사용자가 자동 ​​갱신에 등록되어 있기 때문에 Microsoft Store는 2021년 8월 26일경에 처리된 결제로 구독 갱신을 시도합니다. 사용자 계정이 구독 갱신을 완료할 수 없는 경우 구독 상태가 'InDunning'으로 변경되지만 사용자는 유예 기간이 끝날 때까지 구독 혜택에 계속 액세스해야 합니다. 유예 기간 종료(2021년 9월 8일)에 상점에서 갱신 구매를 완료할 수 없는 경우 상태가 여전히 'InDunning'인 경우에도 서비스에서 더 이상 사용자에게 구독 혜택을 부여하지 않습니다. 유예 기간이 지나면 사용자는 구독 재구매 또는 재등록이 차단되며 활성 구독을 다시 얻으려면 결제 수단을 수정해야 합니다. 유예 기간 동안 2주간의 급여를 받았기 때문에 지금은 지불해야 할 적자가 있습니다. 사용자가 계정의 결제 방법을 해결하면 이전에 사용한 유예 기간을 충당하기 위해 다음 구독 기간에서 2주가 제거됩니다.

연속 토큰으로 나머지 결과 요청

쿼리에 단일 응답에서 반환할 수 있는 것보다 더 많은 결과가 있는 경우 초기 쿼리 응답에는 continuationToken이 있습니다. 그런 다음 이전 요청 본문의 복사본에 연속 토큰을 추가하여 후속 요청에서 이 연속 토큰을 사용할 수 있습니다.

연속 요청 예제:

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "continuationToken":"[Continuation Token]",
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

관련 항목

purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

서비스에서 제품 관리

서비스에서 환불 및 지불 거절 관리

Microsoft Store API를 사용하여 서비스 인증

PublisherQuery(Collections v9)를 사용하여 사용자 제품 및 자격 쿼리