- Resource: Order
- State
- BuyerAddress
- OrderDetails
- LineItem
- OneTimePurchaseDetails
- SubscriptionDetails
- OfferPhase
- PaidAppDetails
- OrderHistory
- ProcessedEvent
- CancellationEvent
- RefundEvent
- RefundDetails
- RefundReason
- PartialRefundEvent
- State
- PointsDetails
- Methods
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 ( |
Fields | |
---|---|
lineItems[] |
The individual line items making up this order. |
orderId |
The order ID. |
purchaseToken |
The token provided to the user's device when the subscription or item was purchased. |
state |
The state of the order. |
createTime |
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: |
lastEventTime |
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: |
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 |
The final amount paid by the customer, taking into account discounts and taxes. |
tax |
The total tax paid as a part of this order. |
orderDetails |
Detailed information about the order at creation time. |
orderHistory |
Details about events which modified the order. |
developerRevenueInBuyerCurrency |
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 |
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 |
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 |
Two letter country code based on ISO-3166-1 Alpha-2 (UN country codes). |
buyerPostcode |
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 |
Indicates whether the listed price was tax inclusive or not. |
LineItem
Details of a line item.
JSON representation |
---|
{ "productTitle": string, "productId": string, "listingPrice": { object ( |
Fields | |
---|---|
productTitle |
Developer-specified name of the product. Displayed in buyer's locale. Example: coins, monthly subscription, etc. |
productId |
The purchased product ID or in-app SKU (for example, 'monthly001' or 'com.some.thing.inapp1'). |
listingPrice |
Item's listed price on Play Store, this may or may not include tax. Excludes any discounts or promotions. |
total |
The total amount paid by the user for this line item, taking into account discounts and tax. |
tax |
The tax paid for this line item. |
Union field
|
|
oneTimePurchaseDetails |
Details of a one-time purchase. |
subscriptionDetails |
Details of a subscription purchase. |
paidAppDetails |
Details of a paid app purchase. |
OneTimePurchaseDetails
Details of a one-time purchase.
JSON representation |
---|
{ "quantity": integer, "offerId": string } |
Fields | |
---|---|
quantity |
The number of items purchased (for multi-quantity item purchases). |
offerId |
The offer ID of the one-time purchase offer. |
SubscriptionDetails
Details of a subscription purchase.
JSON representation |
---|
{
"basePlanId": string,
"offerId": string,
"offerPhase": enum ( |
Fields | |
---|---|
basePlanId |
The base plan ID of the subscription. |
offerId |
The offer ID for the current subscription offer. |
offerPhase |
The pricing phase for the billing period funded by this order. |
servicePeriodStartTime |
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: |
servicePeriodEndTime |
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: |
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 ( |
Fields | |
---|---|
partialRefundEvents[] |
Details of the partial refund events for this order. |
processedEvent |
Details of when the order was processed. |
cancellationEvent |
Details of when the order was canceled. |
refundEvent |
Details of when the order was fully refunded. |
ProcessedEvent
Details of when the order was processed.
JSON representation |
---|
{ "eventTime": string } |
Fields | |
---|---|
eventTime |
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: |
CancellationEvent
Details of when the order was canceled.
JSON representation |
---|
{ "eventTime": string } |
Fields | |
---|---|
eventTime |
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: |
RefundEvent
Details of when the order was fully refunded.
JSON representation |
---|
{ "eventTime": string, "refundDetails": { object ( |
Fields | |
---|---|
eventTime |
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: |
refundDetails |
Details for the full refund. |
refundReason |
The reason the order was refunded. |
RefundDetails
Details for a partial or full refund.
JSON representation |
---|
{ "total": { object ( |
Fields | |
---|---|
total |
The total amount refunded, including tax. |
tax |
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 ( |
Fields | |
---|---|
createTime |
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: |
processTime |
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: |
state |
The state of the partial refund. |
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 ( |
Fields | |
---|---|
pointsOfferId |
ID unique to the play points offer in use for this order. |
pointsCouponValue |
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 |
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 |
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 |
|
---|---|
|
Get order details for a list of orders. |
|
Get order details for a single order. |
|
Refunds a user's subscription or in-app purchase order. |