사용자의 구독 청구 상태 변경Change the billing state of a subscription for a user

Microsoft Store 구매 API에서 이 메서드를 사용하여 지정된 사용자의 구독 추가 기능 청구 상태를 변경할 수 있습니다.Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. 구독을 취소, 연장, 환불 요청, 자동 갱신을 중지할 수 있습니다.You can cancel, extend, refund, or disable automatic renewal for a subscription.

참고

이 메서드는 UWP(유니버설 Windows 플랫폼) 앱에 대한 구독 추가 기능을 만들 수 있도록 Microsoft가 프로비전한 개발자 계정에서만 사용할 수 있습니다.This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. 구독 추가 기능은 현재 대부분의 개발자 계정에서 사용할 수 없습니다.Subscription add-ons are currently not available to most developer accounts.

필수 구성 요소Prerequisites

이 메서드를 사용하려면 다음이 필요합니다.To use this method, you will need:

  • 대상 URI 값이 https://onestore.microsoft.com인 Azure AD 액세스 토큰.An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • 변경할 구독에 대한 권한을 갖고 있는 사용자의 ID를 나타내는 Microsoft Store ID 키.A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

자세한 내용은 서비스에서 제품 권리 유형 관리를 참조하세요.For more information, see Manage product entitlements from a service.

요청Request

요청 구문Request syntax

메서드Method 요청 URIRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

요청 헤더Request header

헤더Header 형식Type 설명Description
권한 부여Authorization 문자열string 필수.Required. 폼에서 Azure AD 액세스 토큰 전달자 < 토큰>합니다.The Azure AD access token in the form Bearer <token>.
호스트Host 문자열string purchase.mp.microsoft.com 값으로 설정해야 합니다.Must be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length 숫자number 요청 본문의 길이입니다.The length of the request body.
Content-TypeContent-Type 문자열string 요청 및 응답 유형을 지정합니다.Specifies the request and response type. 현재 application/json 값만 지원됩니다.Currently, the only supported value is application/json.

요청 매개 변수Request parameters

이름Name 형식Type 설명Description 필수Required
recurrenceIdrecurrenceId 문자열string 변경하려는 구독의 ID입니다.The ID of the subscription you want to change. 이 ID를 가져오려면 호출 합니다 사용자에 대 한 구독을 얻으려면 메서드를 변경 하려는 구독 추가 기능을 해당 하는 응답 본문 항목을 식별 하 고 값을 사용 합니다 id 항목에 대 한 필드.To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. Yes

요청 본문Request body

필드Field 형식Type 설명Description 필수Required
b2bKeyb2bKey 문자열string 구독을 변경할 사용자의 ID를 나타내는 Microsoft Store ID 키입니다.The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. Yes
changeTypechangeType 문자열string 수행하려는 변경 유형을 식별하는 다음 문자열 중 하나입니다.One of the following strings that identifies the type of change you want to make:
  • 취소: 구독을 취소합니다.Cancel: Cancels the subscription.
  • 확장: 구독을 확장합니다.Extend: Extends the subscription. 이 값을 지정하는 경우 extensionTimeInDays 매개 변수도 포함해야 합니다.If you specify this value, you must also include the extensionTimeInDays parameter.
  • 환불: 고객에 게 구독을 환불 합니다.Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew: 구독에 대 한 자동 갱신을 사용 하지 않도록 설정 합니다.ToggleAutoRenew: Disables automatic renewal for the subscription. 현재 구독의 자동 갱신이 비활성화되어 있으면 이 값이 아무 것도 수행하지 않습니다.If automatic renewal is currently disabled for the subscription, this value does nothing.
Yes
extensionTimeInDaysextensionTimeInDays 문자열string changeType 매개 변수 값이 연장이면 이 매개 변수는 구독을 연장하는 일 수를 지정합니다.If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. changeType의 값이 연장이면 예, 그렇지 않으면 아니요입니다.Yes, if changeType has the value Extend; otherwise, no.

요청 예제Request example

다음 예제는 이 메서드를 사용하여 구독 기간을 5일 연장하는 방법을 보여 줍니다.The following example demonstrates how to use this method to extend the subscription period by 5 days. b2bKey 값을 변경할 구독의 사용자 ID를 나타내는 Microsoft Store ID 키로 바꿉니다.Replace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

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"
}

응답Response

이 메서드는 수정된 필드를 포함하여 수정된 구독 추가 기능에 대한 정보가 포함된 JSON 응답 본문을 반환합니다.This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. 다음 예제에서는 이 메서드의 응답 본문을 보여 줍니다.The following example demonstrates a response body for this method.

{
  "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"
    }
  ]
}

응답 본문Response body

응답 본문에는 다음 데이터가 포함됩니다.The response body contains the following data.

Value 형식Type 설명Description
autoRenewautoRenew 부울Boolean 현재 구독 기간이 종료되면 구독을 자동으로 갱신할 것인지 여부를 나타냅니다.Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary 문자열string 이 구독과 연결된 권한의 수취인 ID입니다.The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime 문자열string 구독이 만료되는 날짜 및 시간이며, ISO 8601 형식입니다.The date and time the subscription will expire, in ISO 8601 format. 이 필드는 구독이 특정 상태일 때만 사용할 수 있습니다.This field is only available when the subscription is in certain states. 만료 시간은 일반적으로 현재 상태가 만료되는 시간을 나타냅니다.The expiration time usually indicates when the current state expires. 예를 들어 활성 구독의 경우 만료 날짜는 다음 자동 갱신이 이루어지는 시간을 나타냅니다.For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace 문자열string 날짜 및 시간 유예 기간은 ISO 8601 형식으로 포함 하 여 구독이 만료 됩니다.The date and time the subscription will expire including the grace period, in ISO 8601 format. 이 값 경우 통해 해당 사용자 구독 갱신에 실패 한 후 구독에 대 한 액세스를 잃게 됩니다.This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid 문자열string 구독의 ID입니다.The ID of the subscription. 이 값을 사용하여 change the billing state of a subscription for a user 메서드를 호출할 때 수정할 구독을 나타냅니다.Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial 부울Boolean 구독이 평가판인지 여부를 나타냅니다.Indicates whether the subscription is a trial.
lastModifiedlastModified 문자열string 구독이 마지막으로 수정된 날짜 및 시간이며, ISO 8601 형식입니다.The date and time the subscription was last modified, in ISO 8601 format.
출시market 문자열string 사용자가 구독을 획득한 국가 코드입니다(두 문자로 된 ISO 3166-1 alpha-2 형식).The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId 문자열string Microsoft Store 카탈로그에서 구독 추가 기능을 나타내는 제품Store ID입니다.The Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId 문자열string Microsoft Store 카탈로그에서 구독 추가 기능을 나타내는 SKUStore ID입니다.The Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. SKU에 대한 스토어 ID의 예는 0010입니다.An example Store ID for a SKU is 0010.
startTimestartTime 문자열string 구독의 시작 날짜 및 시간이며, ISO 8601 형식입니다.The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState 문자열string 다음 값 중 하나입니다.One of the following values:
  • 없음:  영구 구독을 나타냅니다.None:  This indicates a perpetual subscription.
  • 활성:  구독이 활성 상태이며 사용자가 서비스를 사용할 수 있습니다.Active:  The subscription is active and the user is entitled to use the services.
  • 비활성:  구독의 만료 날짜가 지났으며 사용자가 구독의 자동 갱신 옵션을 해제했습니다.Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • 취소됨:  만료 날짜 이전에 환불과 함께 또는 환불 없이 구독이 의도적으로 종료되었습니다.Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  구독이 재촉 중(즉, 구독 만료 날짜가 얼마 남지 않아 Microsoft에서 구독을 자동 갱신하기 위한 금액을 취득하려 시도하는 중)입니다.InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • 실패:  재촉 기간이 종료되었으며 여러 차례 시도 후 구독 갱신에 실패했습니다.Failed:  The dunning period is over and the subscription failed to renew after several attempts.

참고:Note:

  • 비활성/취소됨/실패는 최종 상태입니다.Inactive/Canceled/Failed are terminal states. 구독이 이러한 상태 중 하나가 되면 사용자는 구독을 재구매하여 다시 활성화해야 합니다.When a subscription enters one of these states, the user must repurchase the subscription to activate it again. 사용자는 이러한 상태의 서비스를 사용할 수 없습니다.The user is not entitled to use the services in these states.
  • 구독 상태가 취소됨이면 expirationTime이 취소된 날짜 및 시간으로 업데이트됩니다.When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • 구독의 ID는 전체 수명 주기 동안 그대로 유지됩니다.The ID of the subscription will remain the same during its entire lifetime. 자동 갱신 옵션이 켜져 있든 꺼져 있든 변경되지 않습니다.It will not change if the auto-renew option is turned on or off. 최종 상태에 도달한 후 사용자가 구독을 재구매하는 경우 새 구독 ID가 생성됩니다.If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • 각 구독에서 작업을 수행하려면 구독 ID를 사용하여야 합니다.The ID of a subscription should be used to execute any operation on an individual subscription.
  • 사용자가 구독을 취소 또는 중단한 후 구독을 재구매하는 경우 해당 사용자에 대한 결과를 쿼리하면 두 개 항목(하나는 최종 상태의 기존 구독 ID, 다른 하나는 활성 상태의 새 구독 ID)을 받게 됩니다.When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • recurrenceState 업데이트가 몇 분(때로는 몇 시간) 지연될 수 있으므로 항상 recurrenceState와 expirationTime을 모두 확인하는 것이 좋습니다.It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate 문자열string 사용자의 구독이 취소된 날짜 및 시간이며, ISO 8601 형식입니다.The date and time the user's subscription was cancelled, in ISO 8601 format.