REST Resource: orders

Resource: Order

The Order resource encapsulates comprehensive information about a transaction made on Google Play. It includes a variety of attributes that provide details about the order itself, the products purchased, and the history of events related to the order.

The Orders APIs provide real-time access to your order data within the Google Play ecosystem. You can retrieve detailed information and metadata for both one-time and recurring orders, including transaction details like charges, taxes, and refunds, as well as metadata such as pricing phases for subscriptions. The Orders APIs let you automate tasks related to order management, reducing the need for manual checks via the Play Developer Console.

The following are some of the use cases for this API:

  • Real-time order data retrieval - orders.get order details and metadata immediately after a purchase using an order ID.

  • Order update synchronization - Periodically sync order updates to maintain an up-to-date record of order information.

Note:

  • The Orders API calls count towards your Play Developer API quota, which defaults to 200K daily, and may be insufficient to sync extensive order histories.

  • A maximum of 1000 orders can be retrieved per call. Using larger page sizes is recommended to minimize quota usage. Check your quota in the Cloud Console and request more if required.

JSON representation 
{
  "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)
  }
}
Fields
lineItems[]

object (LineItem)

The individual line items making up this order.
orderId

string

The order ID.
purchaseToken

string

The token provided to the user's device when the subscription or item was purchased.
state

enum (State)

The state of the order.
createTime

string (Timestamp format)

The time when the order was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

The time of the last event that occurred on the order.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Address information for the customer, for use in tax computation. When Google is the Merchant of Record for the order, only country is shown.
total

object (Money)

The final amount paid by the customer, taking into account discounts and taxes.
tax

object (Money)

The total tax paid as a part of this order.
orderDetails

object (OrderDetails)

Detailed information about the order at creation time.
orderHistory

object (OrderHistory)

Details about events which modified the order.
developerRevenueInBuyerCurrency

object (Money)

Your revenue for this order in the buyer's currency, including deductions of partial refunds, taxes and fees. Google deducts standard transaction and third party fees from each sale, including VAT in some regions.
pointsDetails

object (PointsDetails)

Play points applied to the order, including offer information, discount rate and point values.

State

The state of the order.

Enums
STATE_UNSPECIFIED State unspecified. This value is not used.
PENDING Order has been created and is waiting to be processed.
PROCESSED Order has been successfully processed.
CANCELED Order was canceled before being processed.
PENDING_REFUND Requested refund is waiting to be processed.
PARTIALLY_REFUNDED Part of the order amount was refunded.
REFUNDED The full order amount was refunded.

BuyerAddress

Address information for the customer, for use in tax computation.

JSON representation 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
Fields
buyerState

string

Top-level administrative subdivision of the buyer address country. When Google is the Merchant of Record for the order, this information is not included.
buyerCountry

string

Two letter country code based on ISO-3166-1 Alpha-2 (UN country codes).
buyerPostcode

string

Postal code of an address. When Google is the Merchant of Record for the order, this information is not included.

OrderDetails

Detailed information about the order at creation time.

JSON representation 
{
  "taxInclusive": boolean
}
Fields
taxInclusive

boolean

Indicates whether the listed price was tax inclusive or not.

LineItem

Details of a line item.

JSON representation 
{
  "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.
}
Fields
productTitle

string

Developer-specified name of the product. Displayed in buyer's locale. Example: coins, monthly subscription, etc.
productId

string

The purchased product ID or in-app SKU (for example, 'monthly001' or 'com.some.thing.inapp1').
listingPrice

object (Money)

Item's listed price on Play Store, this may or may not include tax. Excludes any discounts or promotions.
total

object (Money)

The total amount paid by the user for this line item, taking into account discounts and tax.
tax

object (Money)

The tax paid for this line item.

Union field details.

details can be only one of the following:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Details of a one-time purchase.
subscriptionDetails

object (SubscriptionDetails)

Details of a subscription purchase.
paidAppDetails

object (PaidAppDetails)

Details of a paid app purchase.

OneTimePurchaseDetails

Details of a one-time purchase.

JSON representation 
{
  "quantity": integer,
  "offerId": string
}
Fields
quantity

integer

The number of items purchased (for multi-quantity item purchases).
offerId

string

The offer ID of the one-time purchase offer.

SubscriptionDetails

Details of a subscription purchase.

JSON representation 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
Fields
basePlanId

string

The base plan ID of the subscription.
offerId

string

The offer ID for the current subscription offer.
offerPhase

enum (OfferPhase)

The pricing phase for the billing period funded by this order.
servicePeriodStartTime

string (Timestamp format)

The start of the billing period funded by this order. This is a snapshot of the billing/service period start time at the moment the order was processed, and should be used only for accounting.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

The end of the billing period funded by this order. This is a snapshot of the billing/service period end time at the moment the order was processed, and should be used only for accounting. To get the current end time of the subscription service period, use purchases.subscriptionsv2.get.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

OfferPhase

The pricing phase for the entitlement period funded by this order.

Enums
OFFER_PHASE_UNSPECIFIED Offer phase unspecified. This value is not used.
BASE The order funds a base price period.
INTRODUCTORY The order funds an introductory pricing period.
FREE_TRIAL The order funds a free trial period.

PaidAppDetails

This type has no fields.

Details of a paid app purchase.

OrderHistory

Details about events which modified the order.

JSON representation 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
Fields
partialRefundEvents[]

object (PartialRefundEvent)

Details of the partial refund events for this order.
processedEvent

object (ProcessedEvent)

Details of when the order was processed.
cancellationEvent

object (CancellationEvent)

Details of when the order was canceled.
refundEvent

object (RefundEvent)

Details of when the order was fully refunded.

ProcessedEvent

Details of when the order was processed.

JSON representation 
{
  "eventTime": string
}
Fields
eventTime

string (Timestamp format)

The time when the order was processed.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

CancellationEvent

Details of when the order was canceled.

JSON representation 
{
  "eventTime": string
}
Fields
eventTime

string (Timestamp format)

The time when the order was canceled.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

RefundEvent

Details of when the order was fully refunded.

JSON representation 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
Fields
eventTime

string (Timestamp format)

The time when the order was fully refunded.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Details for the full refund.
refundReason

enum (RefundReason)

The reason the order was refunded.

RefundDetails

Details for a partial or full refund.

JSON representation 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
Fields
total

object (Money)

The total amount refunded, including tax.
tax

object (Money)

The amount of tax refunded.

RefundReason

The reason the order was refunded.

Enums
REFUND_REASON_UNSPECIFIED orders.refund reason unspecified. This value is not used.
OTHER The order was refunded for a reason other than the listed reasons here.
CHARGEBACK The order was charged back.

PartialRefundEvent

Details of the partial refund events for this order.

JSON representation 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
Fields
createTime

string (Timestamp format)

The time when the partial refund was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

The time when the partial refund was processed.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
state

enum (State)

The state of the partial refund.
refundDetails

object (RefundDetails)

Details for the partial refund.

State

The state of the partial refund.

Enums
STATE_UNSPECIFIED State unspecified. This value is not used.
PENDING The partial refund has been created, but not yet processed.
PROCESSED_SUCCESSFULLY The partial refund was processed successfully.

PointsDetails

Details relating to any Play Points applied to an order.

JSON representation 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
Fields
pointsOfferId

string

ID unique to the play points offer in use for this order.
pointsCouponValue

object (Money)

The monetary value of a Play Points coupon. This is the discount the coupon provides, which may not be the total amount. Only set when Play Points coupons have been used. E.g. for a 100 points for $2 coupon, this is $2.
pointsDiscountRateMicros

string (int64 format)

The percentage rate which the Play Points promotion reduces the cost by. E.g. for a 100 points for $2 coupon, this is 500,000. Since $2 has an estimate of 200 points, but the actual Points required, 100, is 50% of this, and 50% in micros is 500,000. Between 0 and 1,000,000.
pointsSpent

string (int64 format)

The number of Play Points applied in this order. E.g. for a 100 points for $2 coupon, this is 100. For coupon stacked with base offer, this is the total points spent across both.

Methods

batchget

 Get order details for a list of orders.

get

 Get order details for a single order.

refund

 Refunds a user's subscription or in-app purchase order.