REST Resource: orders

리소스: 주문

주문 리소스는 Google Play에서 이루어진 거래에 관한 포괄적인 정보를 캡슐화합니다. 여기에는 주문 자체, 구매한 제품, 주문과 관련된 이벤트 기록에 관한 세부정보를 제공하는 다양한 속성이 포함됩니다.

주문 API는 Google Play 생태계 내에서 주문 데이터에 실시간으로 액세스할 수 있도록 지원합니다. 청구, 세금, 환불과 같은 거래 세부정보와 정기 결제의 가격 책정 단계와 같은 메타데이터를 포함하여 일회성 주문과 반복 주문 모두에 대한 세부정보와 메타데이터를 가져올 수 있습니다. 주문 API를 사용하면 주문 관리와 관련된 작업을 자동화하여 Play Console을 통한 수동 확인의 필요성을 줄일 수 있습니다.

다음은 이 API의 사용 사례입니다.

  • 실시간 주문 데이터 검색 - 주문 ID를 사용하여 구매 직후 주문 세부정보 및 메타데이터를 가져옵니다.

  • 주문 업데이트 동기화 - 주문 정보를 최신 상태로 유지하기 위해 주문 업데이트를 주기적으로 동기화합니다.

참고:

  • 주문 API 호출은 Play Developer API 할당량에 포함되며, 기본적으로 일일 20만 개로 설정되어 있어 광범위한 주문 기록을 동기화하기에 충분하지 않을 수 있습니다.

  • 호출당 최대 1,000개의 주문을 가져올 수 있습니다. 할당량 사용을 최소화하려면 더 큰 페이지 크기를 사용하는 것이 좋습니다. Cloud Console에서 할당량을 확인하고 필요한 경우 추가 할당량을 요청하세요.

JSON 표현 
{
  "lineItems": [
    {
      object (LineItem)
    }
  ],
  "orderId": string,
  "purchaseToken": string,
  "state": enum (State),
  "createTime": string,
  "lastEventTime": string,
  "buyerAddress": {
    object (BuyerAddress)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },
  "orderDetails": {
    object (OrderDetails)
  },
  "orderHistory": {
    object (OrderHistory)
  },
  "developerRevenueInBuyerCurrency": {
    object (Money)
  },
  "pointsDetails": {
    object (PointsDetails)
  }
}
필드
lineItems[]

object (LineItem)

이 주문을 구성하는 개별 광고 항목입니다.
orderId

string

주문 ID입니다.
purchaseToken

string

정기 결제 또는 상품이 구매되었을 때 사용자 기기에 제공된 토큰입니다.
state

enum (State)

주문의 상태입니다.
createTime

string (Timestamp format)

주문이 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
lastEventTime

string (Timestamp format)

주문에서 발생한 마지막 이벤트의 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
buyerAddress

object (BuyerAddress)

세금 계산에 사용할 고객의 주소 정보입니다. Google이 주문의 등록된 판매자인 경우 국가만 표시됩니다.
total

object (Money)

할인 및 세금을 감안하여 고객이 지불한 최종 금액입니다.
tax

object (Money)

이 주문의 일환으로 지불된 총 세금입니다.
orderDetails

object (OrderDetails)

생성 시점의 주문에 관한 상세 정보입니다.
orderHistory

object (OrderHistory)

주문을 수정한 이벤트에 관한 세부정보입니다.
developerRevenueInBuyerCurrency

object (Money)

부분 환불, 세금, 수수료 공제를 포함한 구매자 통화의 이 주문에 대한 수익입니다. Google에서는 각 판매 대금에서 표준 거래 및 서드 파티 수수료를 공제합니다. 여기에는 일부 국가의 VAT도 포함됩니다.
pointsDetails

object (PointsDetails)

주문에 적용된 Play 포인트입니다. 혜택 정보, 할인율, 포인트 값이 포함됩니다.

주

주문의 상태입니다.

열거형
STATE_UNSPECIFIED 상태가 지정되지 않았습니다. 이 값은 사용되지 않습니다.
PENDING 주문이 생성되었으며 처리 대기 중입니다.
PROCESSED 주문이 성공적으로 처리되었습니다.
CANCELED 주문이 처리되기 전에 취소되었습니다.
PENDING_REFUND 요청된 환불이 처리 대기 중입니다.
PARTIALLY_REFUNDED 주문 금액의 일부가 환불되었습니다.
REFUNDED 주문 금액 전액이 환불되었습니다.

BuyerAddress

세금 계산에 사용할 고객의 주소 정보입니다.

JSON 표현 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
필드
buyerState

string

구매자 주소지 국가의 최상위 수준 관리 하위 분류입니다. Google이 주문의 등록된 판매자인 경우 이 정보는 포함되지 않습니다.
buyerCountry

string

ISO-3166-1 Alpha-2에 따른 두 글자 국가 코드 (UN 국가 코드)입니다.
buyerPostcode

string

주소의 우편번호입니다. Google이 주문의 등록된 판매자인 경우 이 정보는 포함되지 않습니다.

OrderDetails

생성 시점의 주문에 관한 상세 정보입니다.

JSON 표현 
{
  "taxInclusive": boolean
}
필드
taxInclusive

boolean

정가가 세금 포함 가격인지를 나타냅니다.

LineItem

광고 항목의 세부정보입니다.

JSON 표현 
{
  "productTitle": string,
  "productId": string,
  "listingPrice": {
    object (Money)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },

  // Union field details can be only one of the following:
  "oneTimePurchaseDetails": {
    object (OneTimePurchaseDetails)
  },
  "subscriptionDetails": {
    object (SubscriptionDetails)
  },
  "paidAppDetails": {
    object (PaidAppDetails)
  }
  // End of list of possible types for union field details.
}
필드
productTitle

string

개발자가 지정한 제품 이름입니다. 구매자의 언어로 표시됩니다. 코인, 월간 정기 결제 등을 예로 들 수 있습니다.
productId

string

구매한 제품 ID 또는 인앱 SKU입니다 (예: 'monthly001' 또는 'com.some.thing.inapp1').
listingPrice

object (Money)

Play 스토어에 표시된 상품 가격입니다. 세금이 포함될 수도 있고 포함되지 않을 수도 있습니다. 할인이나 프로모션을 제외한 가격입니다.
total

object (Money)

할인 및 세금을 감안하여 사용자가 이 항목에 지불한 총 금액입니다.
tax

object (Money)

이 항목에 지불한 세금입니다.

통합 필드 details.

details는 다음 중 하나여야 합니다.
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

일회성 구매의 세부정보입니다.
subscriptionDetails

object (SubscriptionDetails)

정기 결제 구매의 세부정보입니다.
paidAppDetails

object (PaidAppDetails)

유료 앱 구매의 세부정보입니다.

OneTimePurchaseDetails

일회성 구매의 세부정보입니다.

JSON 표현 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "rentalDetails": {
    object (RentalDetails)
  }
}
필드
quantity

integer

구매한 상품의 수 (복수 상품 구매의 경우)입니다.
offerId

string

일회성 구매 혜택의 혜택 ID입니다.
purchaseOptionId

string

구매 옵션의 ID입니다. 이 필드는 구매 옵션과 변형 제품 모두에 설정됩니다. 구매 옵션의 경우 이 ID는 구매 옵션 자체를 식별합니다. 변형 혜택의 경우 이 ID는 연결된 구매 옵션을 나타내며 offerId와 함께 변형 혜택을 식별합니다.
rentalDetails

object (RentalDetails)

대여 구매의 세부정보입니다. 대여 구매인 경우에만 설정됩니다.

RentalDetails

이 유형에는 필드가 없습니다.

대여 구매의 세부정보입니다.

SubscriptionDetails

정기 결제 구매의 세부정보입니다.

JSON 표현 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
필드
basePlanId

string

정기 결제의 기본 요금제 ID입니다.
offerId

string

현재 정기 결제 혜택의 혜택 ID입니다.
offerPhase

enum (OfferPhase)

이 주문에서 결제한 결제 기간의 가격 책정 단계입니다.
servicePeriodStartTime

string (Timestamp format)

이 주문에서 결제한 결제 기간의 시작 시점입니다. 이 시점은 주문이 처리되는 순간의 결제/서비스 기간 시작 시점을 의미하며, 회계 목적으로만 사용해야 합니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
servicePeriodEndTime

string (Timestamp format)

이 주문에서 결제한 결제 기간의 종료 시점입니다. 이 시점은 주문이 처리되는 순간의 결제/서비스 기간 종료 시점을 의미하며, 회계 목적으로만 사용해야 합니다. 정기 결제 서비스 기간의 현재 종료 시점을 가져오려면 purchases.subscriptionsv2.get을 사용하세요.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

OfferPhase

이 주문에서 결제한 이용 기간의 가격 책정 단계입니다.

열거형
OFFER_PHASE_UNSPECIFIED 혜택 기간이 지정되지 않았습니다. 이 값은 사용되지 않습니다.
BASE 주문이 기본 가격 기간 동안 결제됩니다.
INTRODUCTORY 신규 할인 가격 기간 동안 주문이 결제됩니다.
FREE_TRIAL 무료 체험 기간 동안 주문이 결제됩니다.

PaidAppDetails

이 유형에는 필드가 없습니다.

유료 앱 구매의 세부정보입니다.

OrderHistory

주문을 수정한 이벤트에 관한 세부정보입니다.

JSON 표현 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
필드
partialRefundEvents[]

object (PartialRefundEvent)

이 주문의 부분 환불 이벤트에 관한 세부정보입니다.
processedEvent

object (ProcessedEvent)

주문이 처리된 시점에 관한 세부정보입니다.
cancellationEvent

object (CancellationEvent)

주문이 취소된 시점에 관한 세부정보입니다.
refundEvent

object (RefundEvent)

주문이 전액 환불된 시점에 관한 세부정보입니다.

ProcessedEvent

주문이 처리된 시점에 관한 세부정보입니다.

JSON 표현 
{
  "eventTime": string
}
필드
eventTime

string (Timestamp format)

주문이 처리된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

CancellationEvent

주문이 취소된 시점에 관한 세부정보입니다.

JSON 표현 
{
  "eventTime": string
}
필드
eventTime

string (Timestamp format)

주문이 취소된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

RefundEvent

주문이 전액 환불된 시점에 관한 세부정보입니다.

JSON 표현 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
필드
eventTime

string (Timestamp format)

주문이 전액 환불된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
refundDetails

object (RefundDetails)

전액 환불의 세부정보입니다.
refundReason

enum (RefundReason)

주문이 환불된 이유입니다.

RefundDetails

부분 또는 전액 환불의 세부정보입니다.

JSON 표현 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
필드
total

object (Money)

세금을 포함한 환불 총액입니다.
tax

object (Money)

환불된 세금 금액입니다.

RefundReason

주문이 환불된 이유입니다.

열거형
REFUND_REASON_UNSPECIFIED orders.refund 이유가 지정되지 않았습니다. 이 값은 사용되지 않습니다.
OTHER 여기에 명시된 이유 이외의 이유로 주문이 환불되었습니다.
CHARGEBACK 주문에 대한 지불이 거절되었습니다.

PartialRefundEvent

이 주문의 부분 환불 이벤트에 관한 세부정보입니다.

JSON 표현 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
필드
createTime

string (Timestamp format)

부분 환불이 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
processTime

string (Timestamp format)

부분 환불이 처리된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
state

enum (State)

부분 환불의 상태입니다.
refundDetails

object (RefundDetails)

부분 환불의 세부정보입니다.

주

부분 환불의 상태입니다.

열거형
STATE_UNSPECIFIED 상태가 지정되지 않았습니다. 이 값은 사용되지 않습니다.
PENDING 부분 환불이 생성되었으나 아직 처리되지 않았습니다.
PROCESSED_SUCCESSFULLY 부분 환불이 처리되었습니다.

PointsDetails

주문에 적용된 Play 포인트와 관련된 세부정보입니다.

JSON 표현 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
필드
pointsOfferId

string

이 주문에 사용된 Play 포인트 혜택의 고유 ID입니다.
pointsCouponValue

object (Money)

Play Points 쿠폰의 금전적 가치입니다. 쿠폰에서 제공하는 할인 금액입니다. 총 금액이 아닐 수 있습니다. Play Points 쿠폰이 사용된 경우에만 설정됩니다. 예를 들어 100포인트당 2달러 쿠폰의 경우 2달러입니다.
pointsDiscountRateMicros

string (int64 format)

Play Points 프로모션으로 비용이 절감되는 비율입니다. 예를 들어 $2 쿠폰의 경우 100포인트이므로 500,000입니다. $2의 예상 포인트는 200포인트이지만 실제 필요한 포인트는 100으로 예상 포인트의 50% 이고, 마이크로의 50% 는 500,000입니다. 0~1,000,000 사이
pointsSpent

string (int64 format)

이 주문에 적용된 Play 포인트 수입니다. 예를 들어 2달러 쿠폰의 경우 100포인트입니다. 기본 혜택과 중복된 쿠폰의 경우 두 혜택에서 사용된 총 포인트입니다.

메서드

batchget

 주문 목록의 주문 세부정보를 가져옵니다.

get

 단일 주문의 주문 세부정보를 가져옵니다.

refund

 사용자의 정기 결제 또는 인앱 구매 주문을 환불합니다.