> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# purchase.mp.microsoft.com/v7.0/purchases/grant

> 게임 서비스가 Microsoft Entra ID 인증을 사용하여 무료 앱 또는 추가 기능을 사용자 계정에 직접 부여할 수 있게 하는 Microsoft Store v8 purchases/grant API입니다.

Microsoft Store 구매 API를 사용하여 무료 앱 또는 추가 기능을 사용자 계정에 부여합니다.

무료 제품만 사용자 계정에 직접 부여할 수 있습니다.
유료 제품에 대한 부여 시도는 오류를 반환합니다.

## 필수 구성 요소

[서비스 간 API의 필수 구성 요소](/ko/publishing/xstore-commerce/xstore-authenticating-service)를 검토하세요.

이 API는 Microsoft Entra ID 인증 유형만 지원합니다.

제품 구성이 Partner Center에 게시되지 않은 경우, 요청은 성공하지만 결과가 반환되지 않을 수 있습니다.

## 요청

### 요청 구문

| 메서드 | 요청 URI |
| - | - |
| `POST` | `https://purchase.mp.microsoft.com/v7.0/purchases/grant` |

### 요청 헤더

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

### 요청 본문

| 매개 변수 | 형식 | 설명 | 필수 |
| - | - | - | - |
| `availabilityId` | `string` | Microsoft Store 카탈로그에서 부여할 제품의 가용성 ID입니다. | 예 |
| `b2bKey` | `string` | 제품을 부여하려는 사용자의 ID를 나타내는 [User Store ID 키](/ko/publishing/xstore-commerce/xstore-requesting-userstoreid#step-4-create-a-user-store-id-key)입니다. | 예 |
| `devOfferId` | `string` | 구매 후 Collection 항목에 표시되는 개발자 지정 제안 ID입니다. | 아니요 |
| `language` | `string` | 사용자의 언어입니다. | 예 |
| `market` | `string` | 사용자의 시장입니다. | 예 |
| `orderId` | `GUID` | 주문에 대해 생성된 GUID입니다. 이 값은 사용자에 대해 고유하지만, 모든 주문에서 고유할 필요는 없습니다. | 예 |
| `productId` | `string` | Microsoft Store 카탈로그에 있는 [제품](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)의 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)입니다. 제품의 Store ID 예는 9NBLGGH42CFD입니다. | 예 |
| `quantity` | `int` | 구매할 수량입니다. 현재 지원되는 유일한 값은 1입니다. 지정하지 않으면 기본값은 1입니다. | 아니요 |
| `skuId` | `string` | Microsoft Store 카탈로그에 있는 제품 [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)의 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)입니다. SKU의 Store ID 예는 0010입니다. | 예 |
| `sbx` | `string` | UserStoreId로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없으면 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다. | 아니요 |

### 요청 예제

```syntax theme={null}
POST https://purchase.mp.microsoft.com/v7.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK...
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK...",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
    "sbx" : "XDKS.1"
}
```

## 응답

### 응답 본문

| 매개 변수 | 형식 | 설명 | 필수 |
| - | - | - | - |
| `clientContext` | `ClientContextV8` | 주문에 대한 클라이언트 컨텍스트 정보입니다. Microsoft Entra ID 토큰의 `clientID` 값으로 할당됩니다. | 예 |
| `createdtime` | `datetimeoffset` | 주문이 생성된 시간입니다. | 예 |
| `currencyCode` | `string` | `totalAmount` 및 `totalTaxAmount`의 통화 코드입니다. 무료 항목에는 해당되지 않습니다. | 예 |
| `friendlyName` | `string` | 주문의 표시 이름입니다. Microsoft Store 구매 API를 사용하여 생성된 주문에는 해당되지 않습니다. | 예 |
| `isPIRequired` | `boolean` | 구매 주문의 일부로 결제 수단(PI)이 필요한지 여부를 나타냅니다. | 예 |
| `language` | `string` | 주문의 언어 ID입니다(예: "en"). | 예 |
| `market` | `string` | 주문의 시장 ID입니다(예: "US"). | 예 |
| `orderId` | `string` | 특정 사용자의 주문을 식별하는 ID입니다. | 예 |
| `orderLineItems` | `list<OrderLineItemV8>` | 주문의 품목 목록입니다. 일반적으로 주문당 하나의 품목이 있습니다. | 예 |
| `orderState` | `string` | 주문의 상태입니다. 유효한 상태는 `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack`, `Canceled`입니다. | 예 |
| `orderValidityEndTime` | `string` | 주문 가격이 종료되는 시점입니다. 무료 앱에는 해당되지 않습니다. | 예 |
| `orderValidityStartTime` | `string` | 주문 가격이 시작되는 시점입니다. 무료 앱에는 해당되지 않습니다. | 예 |
| `purchaser` | `IdentityV6` | 구매자의 ID를 설명하는 개체입니다. | 예 |
| `totalAmount` | `decimal` | 세금을 포함한 주문 내 모든 항목의 총 구매 금액입니다. | 예 |
| `totalAmountBeforeTax` | `decimal` | 세금 적용 전 주문 내 모든 항목의 총 구매 금액입니다. | 예 |
| `totalChargedToCsvTopOffPI` | `decimal` | 별도의 결제 수단과 저장된 값(CSV(쉼표로 구분된 값))을 사용하는 경우 CSV에 청구된 금액입니다. | 예 |
| `totalTaxAmount` | `decimal` | 모든 품목에 대한 총 세금 금액입니다. | 예 |

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

| 매개 변수 | 형식 | 설명 | 필수 |
| - | - | - | - |
| `client` | `string` | 주문을 생성한 클라이언트 ID입니다. | 아니요 |

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

| 매개 변수 | 형식 | 설명 | 필수 |
| - | - | - | - |
| `agent` | `IdentityV8` | 품목을 마지막으로 편집한 에이전트입니다. 이 개체에 대한 자세한 내용은 다음 표를 참조하세요. | 아니요 |
| `availabilityId` | `string` | Microsoft Store 카탈로그에서 구매할 제품의 가용성 ID입니다. | 예 |
| `beneficiary` | `IdentityV8` | 주문 수혜자의 ID입니다. | 아니요 |
| `billingState` | `string` | 주문의 청구 상태입니다. 완료되면 `Charged`로 설정됩니다. | 아니요 |
| `campaignId` | `string` | 이 주문의 캠페인 ID입니다. | 아니요 |
| `currencyCode` | `string` | 가격 세부 정보에 사용되는 통화 코드입니다. | 예 |
| `description` | `string` | 품목에 대한 지역화된 설명입니다. | 예 |
| `devofferId` | `string` | 특정 주문의 제안 ID입니다(있는 경우). | 아니요 |
| `fulfillmentDate` | `datetimeoffset` | 처리가 발생한 날짜입니다. | 아니요 |
| `fulfillmentState` | `string` | 항목의 처리 상태입니다. 완료되면 `Fulfilled`로 설정됩니다. | 아니요 |
| `isPIRequired` | `boolean` | 이 품목에 결제 수단이 필요한지 여부를 나타냅니다. | 예 |
| `isTaxIncluded` | `boolean` | 항목의 가격 세부 정보에 세금이 포함되어 있는지 여부를 나타냅니다. | 예 |
| `legacyBillingOrderId` | `string` | 레거시 청구 ID입니다. | 아니요 |
| `lineItemId` | `string` | 이 주문에 있는 항목의 품목 ID입니다. | 예 |
| `listPrice` | `decimal` | 이 주문에 있는 항목의 정가입니다. | 예 |
| `productId` | `string` | Microsoft Store 카탈로그에서 품목을 나타내는 [제품](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)의 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)입니다. 제품의 Store ID 예는 9NBLGGH42CFD입니다. | 예 |
| `productType` | `string` | 제품의 유형입니다. 지원되는 값은 `Durable`, `Application`, `UnmanagedConsumable`입니다. | 예 |
| `quantity` | `int` | 주문한 항목의 수량입니다. | 예 |
| `retailPrice` | `decimal` | 주문한 항목의 소매 가격입니다. | 예 |
| `revenueRecognitionState` | `string` | 수익 인식 상태입니다. | 예 |
| `skuId` | `string` | Microsoft Store 카탈로그에 있는 품목 [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)의 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)입니다. SKU의 Store ID 예는 0010입니다. | 예 |
| `taxAmount` | `decimal` | 품목의 세금 금액입니다. | 예 |
| `taxType` | `string` | 해당 세금의 세금 유형입니다. | 예 |
| `Title` | `string` | 품목의 지역화된 제목입니다. | 예 |
| `totalAmount` | `decimal` | 세금을 포함한 품목의 총 구매 금액입니다. | 예 |

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

| 매개 변수 | 형식 | 설명 | 필수 |
| - | - | - | - |
| `identityType` | `string` | `"pub"` 값을 포함합니다. | 예 |
| `identityValue` | `string` | 지정된 User Store ID 키에 있는 *publisherUserId*의 문자열 값입니다. | 예 |

### 응답 예제

```syntax theme={null}
Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}
```

## 오류 코드

| 코드 | 오류 | 내부 오류 코드 | 설명 |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID 액세스 토큰이 잘못되었습니다. 토큰이 만료되었거나 *appid* 클레임이 없는 경우와 같이 ServiceError 세부 정보에 추가 정보가 포함되는 경우도 있습니다. |
| 401 | Unauthorized | PartnerAadTicketRequired | Microsoft Entra ID 액세스 토큰이 권한 부여 헤더로 서비스에 전달되지 않았습니다. |
| 401 | Unauthorized | InconsistentClientId | User Store ID 키의 `clientId` 클레임과 액세스 토큰의 `appid`가 일치하지 않습니다. |
| 400 | BadRequest | InvalidParameter | 세부 정보에 요청 본문 및 잘못된 값을 가진 필드에 관한 정보가 포함되어 있습니다. |

## 관련 문서

[서비스에서 제품 관리](/ko/publishing/xstore-commerce/xstore-authenticating-service)

[서비스 간 인증을 위한 User Store ID 요청](/ko/publishing/xstore-commerce/xstore-requesting-userstoreid)

[Microsoft Store ID 키 갱신](https://learn.microsoft.com/reference/xstore-renew-a-user-store-id-key)


## Related topics

- [Microsoft Store 서비스 API (콘텐츠)](/ko/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/ko/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/ko/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [X-token 또는 OAuth 2.0을 사용하여 서비스에서 User Store ID 요청](/ko/publishing/xstore-commerce/xstore-requesting-userstoreid-oauth.md)
- [User Store ID 키 갱신](/ko/publishing/xstore-commerce/xstore-renew-userstoreid.md)