다음을 통해 공유

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

  • 아티클

참고 항목

개발 샌드박스를 사용하는 경우 현재 이 API는 구독 제품이 RETAIL 샌드박스에 게시된 경우에만 작동합니다. 구독이 RETAIL에 게시되지 않은 경우 "요청된 카탈로그 제품 데이터를 찾을 수 없습니다"라는 메시지와 함께 HTTP 400 오류 응답이 반환됩니다. 이는 향후 릴리스에서 해결해야 할 작업 항목이 있는 알려진 문제입니다. 그때까지는 이 API를 사용할 수 있도록 프라이빗 플라이트 그룹에 구독을 게시하거나 RETAIL에 숨겨진 구독을 게시해야 합니다.

이 엔드포인트는 Microsoft Store에서 사용자 구독 제품의 청구 상태를 변경하는 데 사용됩니다. 구독에 대한 자동 갱신을 취소, 연장, 환불 또는 비활성화할 수 있습니다.

Microsoft.StoreServices 라이브러리(GitHub)는 StoreServicesClient.RecurrenceChangeAsync API를 통해 이 메서드의 기능을 제공합니다.

사전 요건

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

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

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

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

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

참고 항목

제품 구성이 완료되어 파트너 센터를 통해 게시되지 않은 경우 구매 서비스에 대한 호출은 성공하지만 응답에 결과가 없습니다.

요청

요청 구문

메서드 요청 URI
POST purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

요청 헤더

헤더 형식 설명
Authorization string 필수. Bearer < 토큰> 양식의 Microsoft Entra ID 서비스 액세스 토큰입니다.
Host string 값 purchase.mp.microsoft.com(으)로 설정해야 합니다.
Content-Length number 요청 본문의 길이입니다.
Content-Type string 요청 및 응답 유형을 지정합니다. 현재 지원되는 유일한 값은 application/json입니다.

요청 매개 변수

헤더 형식 설명 필수
recurrenceId string 사용자의 구독에 고유하며 purchase.mp.microsoft.com/v8.0/b2b/recurrence/query에 대한 쿼리 결과에서 가져옵니다. 예

요청 본문

매개 변수 형식 설명 필수
b2bKey string 요청하는 사용자의 ID를 나타내는 사용자 구매 ID입니다. 사용자 저장소 ID 키를 참조하세요. 예
changeType string 변경하려는 유형을 식별합니다. 가능한 변경 유형 값은 아래 표를 참조하십시오. 예
extensionTimeInDays string changeType 매개변수에 Extend 값이 있는 경우 이 매개변수는 구독을 연장할 일 수를 지정합니다. 테스트 시나리오의 경우 구독에서 날짜를 제거하려면 이 숫자가 음수일 수 있습니다. 예, changeType에 Extend 값이 있는 경우 그렇지 않으면 아니요.
sbx string 결과의 범위를 지정해야 하는 샌드박스를 지정하는 UserStoreIds로 인증하기 위한 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증에는 X-Token 내에 Sandbox가 지정되어 있으므로 이 값이 필요하지 않습니다. 아니요

형식 변경 작업

변경 내용 유형 설명
Cancel 구독을 취소합니다.
Extend 구독을 확장합니다. 이 값을 지정하는 경우 요청 본문에 extensionTimeInDays 매개 변수도 포함해야 합니다.
Refund 고객에게 구독을 환불합니다.
ToggleAutoRenew 구독에 대한 자동 갱신을 사용하지 않도록 설정합니다. 현재 구독의 자동 갱신이 비활성화되어 있으면 이 값이 아무 것도 수행하지 않습니다.

요청 예제

다음 예제는 이 메서드를 사용하여 구독 기간을 5일 연장하는 방법을 보여 줍니다. b2bKey 값을 구독을 변경하려는 사용자의 ID를 나타내는 사용자 Store ID 키로 바꿉니다.

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 응답 본문을 반환합니다. 다음 예제에서는 이 메서드의 응답 본문을 보여 줍니다.

참고 항목

개발 샌드박스를 사용하는 경우 현재 이 API는 구독 제품이 RETAIL 샌드박스에 게시된 경우에만 작동합니다. 구독이 RETAIL에 게시되지 않은 경우 "요청된 카탈로그 제품 데이터를 찾을 수 없습니다"라는 메시지와 함께 HTTP 400 오류 응답이 반환됩니다. 이는 향후 릴리스에서 해결해야 할 작업 항목이 있는 알려진 문제입니다. 그때까지는 이 API를 사용할 수 있도록 프라이빗 플라이트 그룹에 구독을 게시하거나 RETAIL에 숨겨진 구독을 게시해야 합니다.

응답 본문

매개 변수 형식 설명 필수
continuationToken string 제품 집합이 여러 개인 경우 페이지 제한에 도달할 때 이 토큰이 반환됩니다. 나머지 제품을 검색하는 후속 호출에서 그 연속 토큰을 지정할 수 있습니다. 아니요
items list<RecurrenceItem> 사용자가 지정된 제품의 배열입니다. 자세한 내용은 다음 표를 참조합니다. 예

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

매개 변수 형식 설명 필수
autoRenew bool 사용자가 다음 청구 주기가 끝날 때 구독을 자동 갱신하도록 등록되었는지를 나타냅니다. 예
beneficiary string 사용자 구매 ID 내 수취인의 게시자 ID입니다. 예
expirationTime DateTime 구독이 만료되거나 만료되는 UTC 날짜 및 시간 예
expirationTimeWithGrace DateTime ExpirationTime에서 자동 갱신이 실패할 경우 사용자의 유예 기간이 종료되는 UTC 날짜 및 시간입니다. 유예 기간 동안 사용자는 여전히 액세스 권한을 가지며 유효한 구독자로 간주되어야 하지만 자동 갱신 결제를 수정해야 한다는 알림을 받습니다. 예
id string 사용자가 소유한 다른 품목에서 이 컬렉션 품목을 식별하는 ID입니다. 이 ID는 제품마다 고유합니다. 예
isTrial bool 제품이 평가판 기간 내에 있는지 여부를 나타냅니다(예: 구독). 예
lastModified DateTime 이 항목이 마지막으로 수정된 UTC 날짜입니다. 예
market string 2자리 ISO 3166 국가/지역 코드에 따라 제품을 구매한 국가/지역입니다. 예: 미국. 예
productId string Microsoft Store 카탈로그내의 제품에 대한 Microsoft Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다. 예
recurrenceState string 되풀이의 현재 상태입니다. 되풀이 상태를 참조하세요. 예
skuId string Microsoft Store 카탈로그에 다중 제공 제품이 있는 경우 특정 SKU 식별자 SKU에 대한 Microsoft Store ID의 예는 0010입니다. 예
startTime DateTime 구독이 유효하게 되었거나 유효하게 될 UTC 날짜입니다. 예
cancellationDate DateTime 구독이 취소된 UTC 날짜입니다. 아니요

되풀이 상태

값 설명
None 영구 구독을 나타냅니다.
Active 구독이 유효하고 사용자가 구독 혜택을 받을 수 있습니다.
Inactive 구독이 만료 날짜가 지났고 사용자가 구독에 대한 자동 갱신 옵션을 해제했습니다.
Canceled 구독은 환불 여부에 관계없이 만료 날짜 전에 의도적으로 종료되었습니다.
InDunning 구독이 독촉 중입니다(즉, 구독 만료가 임박하고 Microsoft가 구독을 자동으로 갱신하기 위해 자금을 확보하려고 합니다). 현재 날짜가 expireTimeWithGrace 값보다 이전인 경우에도 사용자는 구독 혜택을 받을 수 있습니다. 현재 날짜가 expireTimeWithGrace 값 이후인 경우 사용자는 구독 혜택에 액세스할 수 없습니다.
Failed 독촉 기간이 끝났으며 여러 번 시도한 후 구독을 갱신하지 못했습니다.
  • 비활성/취소됨/실패는 최종 상태입니다. 구독이 이러한 상태 중 하나가 되면 사용자는 구독을 다시 구매하여 다시 활성화해야 합니다. 사용자는 이러한 상태에서 서비스를 사용할 수 없습니다.
  • 구독이 취소되면 만료 시간은 취소 날짜와 시간으로 업데이트됩니다.
  • 구독의 ID는 전체 수명 동안 동일하게 유지됩니다. 자동 갱신 옵션이 켜져 있거나 꺼져 있어도 변경되지 않습니다. 사용자가 터미널 상태에 도달한 후 구독을 재구매하면 새 구독 ID가 생성됩니다.
  • 구독 ID는 개별 구독에서 작업을 실행하는 데 사용해야 합니다.
  • 사용자가 구독을 취소하거나 중단한 후 재구매할 때 사용자에 대한 결과를 쿼리하면 두 개의 항목이 표시됩니다. 하나는 터미널 상태의 이전 구독 ID이고 다른 하나는 활성 상태의 새 구독 ID입니다.
  • recurrenceState 업데이트가 몇 분(때로는 몇 시간) 지연될 수 있으므로 항상 recurrenceState와 expirationTime을 모두 확인하는 것이 좋습니다.

응답 예제

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT

{
    "autoRenew": true,
    "beneficiary": "pub:NoUserIdProvided",
    "expirationTime": "2022-03-03T23:59:59.00+00:00",
    "expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
    "id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
    "isTrial": false,
    "lastModified": "2022-03-03T23:19:12.26+00:00",
    "market": "US",
    "productId": "CFQ7TTC0HC8Z",
    "skuId": "0003",
    "startTime": "2022-03-03T00:00:00.00+00:00",
    "recurrenceState": "Active"
}

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

서비스에서 제품 관리

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

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

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