Manage in-app product and subscription purchases, including verification, acknowledgment, and consumption of purchase tokens.
openapi: 3.1.0
info:
title: Google Play Developer Orders Purchases API
description: The Google Play Developer API allows you to perform a number of publishing and app-management tasks. It includes the Subscriptions and In-App Purchases API, which lets you manage in-app purchases and subscriptions, and the Reviews API for retrieving and replying to user reviews. This specification covers the purchases, reviews, and subscriptions resources of the Google Play Developer API v3.
version: '3.0'
termsOfService: https://developers.google.com/terms
contact:
name: Google Play Developer Support
url: https://support.google.com/googleplay/android-developer
license:
name: Creative Commons Attribution 4.0
url: https://creativecommons.org/licenses/by/4.0/
x-logo:
url: https://www.gstatic.com/android/market_images/web/favicon_v2.ico
altText: Google Play
servers:
- url: https://androidpublisher.googleapis.com/androidpublisher/v3
description: Google Play Developer API v3 production endpoint
security:
- oauth2:
- androidpublisher
tags:
- name: Purchases
description: Manage in-app product and subscription purchases, including verification, acknowledgment, and consumption of purchase tokens.
externalDocs:
url: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products
paths:
/applications/{packageName}/purchases/products/{productId}/tokens/{token}:
get:
operationId: getPurchaseProduct
summary: Get In-app Product Purchase Status
description: Checks the purchase and consumption status of an in-app product. Returns the purchase details including the purchase state, consumption state, and order ID.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/purchaseToken'
responses:
'200':
description: Successful response with product purchase details
content:
application/json:
schema:
$ref: '#/components/schemas/ProductPurchase'
examples:
Getpurchaseproduct200Example:
summary: Default getPurchaseProduct 200 response
x-microcks-default: true
value:
kind: example_value
purchaseTimeMillis: example_value
purchaseState: 0
consumptionState: 0
developerPayload: example_value
orderId: '500123'
purchaseType: 0
acknowledgementState: 0
purchaseToken: example_value
productId: '500123'
quantity: 10
obfuscatedExternalAccountId: '500123'
obfuscatedExternalProfileId: '500123'
regionCode: example_value
refundableQuantity: 10
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge:
post:
operationId: acknowledgePurchaseProduct
summary: Acknowledge an In-app Product Purchase
description: Acknowledges a purchase of an in-app item. Purchases that are not acknowledged within three days are automatically refunded.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/purchaseToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductPurchasesAcknowledgeRequest'
examples:
AcknowledgepurchaseproductRequestExample:
summary: Default acknowledgePurchaseProduct request
x-microcks-default: true
value:
developerPayload: example_value
responses:
'204':
description: Purchase acknowledged successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/products/{productId}/tokens/{token}:consume:
post:
operationId: consumePurchaseProduct
summary: Consume an In-app Product Purchase
description: Consumes a purchase for an in-app item. Consumed purchases can be purchased again, making this appropriate for consumable items.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/purchaseToken'
responses:
'204':
description: Purchase consumed successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:
get:
operationId: getPurchaseSubscription
summary: Get Subscription Purchase Status
description: Checks whether a user's subscription purchase is valid and returns its expiry time. Includes information about auto-renewal status, payment state, cancellation reason, and linked purchase token.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/purchaseToken'
responses:
'200':
description: Successful response with subscription purchase details
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPurchase'
examples:
Getpurchasesubscription200Example:
summary: Default getPurchaseSubscription 200 response
x-microcks-default: true
value:
kind: example_value
startTimeMillis: example_value
expiryTimeMillis: example_value
userCancellationTimeMillis: example_value
autoRenewing: true
priceCurrencyCode: example_value
priceAmountMicros: example_value
introductoryPriceInfo:
introductoryPriceCurrencyCode: example_value
introductoryPriceAmountMicros: example_value
introductoryPricePeriod: example_value
introductoryPriceCycles: 10
countryCode: example_value
developerPayload: example_value
paymentState: 0
cancelReason: 0
linkedPurchaseToken: example_value
purchaseType: 0
orderId: '500123'
acknowledgementState: 0
externalAccountId: '500123'
promotionType: 0
promotionCode: example_value
obfuscatedExternalAccountId: '500123'
obfuscatedExternalProfileId: '500123'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge:
post:
operationId: acknowledgePurchaseSubscription
summary: Acknowledge a Subscription Purchase
description: Acknowledges a subscription purchase. Subscriptions that are not acknowledged within three days are automatically refunded.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/purchaseToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPurchasesAcknowledgeRequest'
examples:
AcknowledgepurchasesubscriptionRequestExample:
summary: Default acknowledgePurchaseSubscription request
x-microcks-default: true
value:
developerPayload: example_value
responses:
'204':
description: Subscription purchase acknowledged successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:cancel:
post:
operationId: cancelPurchaseSubscription
summary: Cancel a Subscription Purchase
description: Cancels a user's subscription purchase. The subscription remains valid until its expiration time and will not be auto-renewed.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/purchaseToken'
responses:
'204':
description: Subscription cancelled successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:defer:
post:
operationId: deferPurchaseSubscription
summary: Defer a Subscription Purchase
description: Defers a user's subscription purchase until a specified future expiration time. The user retains access to the subscription content during the deferral period.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/purchaseToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPurchasesDeferRequest'
examples:
DeferpurchasesubscriptionRequestExample:
summary: Default deferPurchaseSubscription request
x-microcks-default: true
value:
deferralInfo:
expectedExpiryTimeMillis: example_value
desiredExpiryTimeMillis: example_value
responses:
'200':
description: Subscription deferred successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPurchasesDeferResponse'
examples:
Deferpurchasesubscription200Example:
summary: Default deferPurchaseSubscription 200 response
x-microcks-default: true
value:
newExpiryTimeMillis: example_value
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:revoke:
post:
operationId: revokePurchaseSubscription
summary: Revoke a Subscription Purchase
description: Refunds and immediately revokes a user's subscription purchase. Access to the subscription is terminated immediately and a refund is issued. This cannot be undone.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/purchaseToken'
responses:
'204':
description: Subscription revoked and refunded successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/subscriptionsv2/tokens/{token}:
get:
operationId: getSubscriptionPurchaseV2
summary: Get Subscription Purchase V2
description: Gets the latest subscription purchase state using the Purchases Subscriptions v2 API. Returns detailed information about the subscription including line items, external account identifiers, and subscription state.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/purchaseToken'
responses:
'200':
description: Successful response with subscription purchase v2 details
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPurchaseV2'
examples:
Getsubscriptionpurchasev2200Example:
summary: Default getSubscriptionPurchaseV2 200 response
x-microcks-default: true
value:
kind: example_value
regionCode: example_value
latestOrderId: '500123'
lineItems:
- productId: '500123'
expiryTime: '2026-01-15T10:30:00Z'
autoRenewingPlan: {}
prepaidPlan: {}
offerDetails: {}
startTime: '2026-01-15T10:30:00Z'
subscriptionState: SUBSCRIPTION_STATE_UNSPECIFIED
linkedPurchaseToken: example_value
pausedStateContext:
autoResumeTime: '2026-01-15T10:30:00Z'
canceledStateContext:
userInitiatedCancellation:
finishTime: '2026-01-15T10:30:00Z'
systemInitiatedCancellation: example_value
developerInitiatedCancellation: example_value
replacementCancellation: example_value
acknowledgementState: ACKNOWLEDGEMENT_STATE_UNSPECIFIED
externalAccountIdentifiers:
externalAccountId: '500123'
obfuscatedExternalAccountId: '500123'
obfuscatedExternalProfileId: '500123'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/purchases/voidedpurchases:
get:
operationId: listVoidedPurchases
summary: List Voided Purchases
description: Lists the purchases that were cancelled, refunded, or charged back. Voided purchases include both in-app product purchases and subscription purchases.
tags:
- Purchases
parameters:
- $ref: '#/components/parameters/packageName'
- name: startTime
in: query
description: The time (in milliseconds since Epoch) of the oldest voided purchase to return. Defaults to 30 days before the current time.
schema:
type: string
format: int64
example: example_value
- name: endTime
in: query
description: The time (in milliseconds since Epoch) of the newest voided purchase to return.
schema:
type: string
format: int64
example: example_value
- name: maxResults
in: query
description: Maximum number of results to return. Default and maximum is 1000.
schema:
type: integer
maximum: 1000
example: 10
- name: startIndex
in: query
description: Index of the first result to return.
schema:
type: integer
example: 10
- name: token
in: query
description: Continuation token for paging through results.
schema:
type: string
example: example_value
- name: type
in: query
description: The type of voided purchases to return. 0 for voided in-app product purchases, 1 for voided subscription purchases.
schema:
type: integer
enum:
- 0
- 1
example: 0
responses:
'200':
description: Successful response with list of voided purchases
content:
application/json:
schema:
$ref: '#/components/schemas/VoidedPurchasesListResponse'
examples:
Listvoidedpurchases200Example:
summary: Default listVoidedPurchases 200 response
x-microcks-default: true
value:
pageInfo:
totalResults: 10
resultPerPage: 10
startIndex: 10
tokenPagination:
nextPageToken: example_value
previousPageToken: example_value
voidedPurchases:
- kind: example_value
purchaseToken: example_value
purchaseTimeMillis: example_value
voidedTimeMillis: example_value
orderId: '500123'
voidedSource: 0
voidedReason: 0
voidedQuantity: 10
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
packageName:
name: packageName
in: path
required: true
description: The package name of the application (e.g., com.example.myapp). This is the unique identifier for the app on Google Play.
schema:
type: string
example: com.example.myapp
purchaseToken:
name: token
in: path
required: true
description: The token provided to the user's device when the purchase was made. Used to uniquely identify a purchase.
schema:
type: string
subscriptionId:
name: subscriptionId
in: path
required: true
description: The subscription ID (e.g., monthly_sub).
schema:
type: string
example: monthly_sub
productId:
name: productId
in: path
required: true
description: The product ID of the in-app product or subscription (e.g., premium_upgrade, monthly_sub).
schema:
type: string
example: premium_upgrade
schemas:
SubscriptionPurchasesDeferRequest:
type: object
description: Request body for deferring a subscription purchase.
properties:
deferralInfo:
$ref: '#/components/schemas/SubscriptionDeferralInfo'
required:
- deferralInfo
SubscriptionDeferralInfo:
type: object
description: Contains the new desired expiry time for a subscription deferral.
properties:
expectedExpiryTimeMillis:
type: string
format: int64
description: The expected expiry time for the subscription. If the current expiry time does not match, the deferral will not occur.
example: example_value
desiredExpiryTimeMillis:
type: string
format: int64
description: The desired next expiry time to assign to the subscription. Must be later than the current expiry time.
example: example_value
required:
- expectedExpiryTimeMillis
- desiredExpiryTimeMillis
SubscriptionPurchaseLineItem:
type: object
description: An individual line item within a v2 subscription purchase. Each line item represents a base plan or offer.
properties:
productId:
type: string
description: The product ID of the subscription.
example: '500123'
expiryTime:
type: string
format: date-time
description: Time at which the subscription line item will expire.
example: '2026-01-15T10:30:00Z'
autoRenewingPlan:
type: object
description: Details for auto-renewing plans.
properties:
autoRenewEnabled:
type: boolean
example: example_value
prepaidPlan:
type: object
description: Details for prepaid plans.
properties:
allowExtendAfterTime:
type: string
format: date-time
example: example_value
offerDetails:
type: object
description: Details of the offer applied to this line item.
properties:
offerTags:
type: array
items:
type: string
basePlanId:
type: string
offerId:
type: string
example: example_value
PageInfo:
type: object
description: Pagination information for list responses.
properties:
totalResults:
type: integer
description: Total number of results available.
example: 10
resultPerPage:
type: integer
description: Maximum number of results per page.
example: 10
startIndex:
type: integer
description: Index of the first result returned.
example: 10
IntroductoryPriceInfo:
type: object
description: Contains the introductory price information for a subscription.
properties:
introductoryPriceCurrencyCode:
type: string
description: ISO 4217 currency code for the introductory price.
example: example_value
introductoryPriceAmountMicros:
type: string
format: int64
description: Introductory price in micro-units of the currency.
example: example_value
introductoryPricePeriod:
type: string
description: Introductory price period in ISO 8601 format (e.g., P1W for one week, P1M for one month).
example: example_value
introductoryPriceCycles:
type: integer
description: Number of billing periods the introductory price applies for.
example: 10
VoidedPurchasesListResponse:
type: object
description: Response containing a list of voided purchases.
properties:
pageInfo:
$ref: '#/components/schemas/PageInfo'
tokenPagination:
$ref: '#/components/schemas/TokenPagination'
voidedPurchases:
type: array
description: List of voided purchases.
items:
$ref: '#/components/schemas/VoidedPurchase'
example: []
ProductPurchase:
type: object
description: Represents an in-app product purchase. Contains the purchase state, consumption status, and order information.
properties:
kind:
type: string
description: Resource type identifier.
const: androidpublisher#productPurchase
example: example_value
purchaseTimeMillis:
type: string
format: int64
description: Time the product was purchased (milliseconds since Epoch).
example: example_value
purchaseState:
type: integer
description: The purchase state of the order. 0 = Purchased, 1 = Canceled, 2 = Pending.
enum:
- 0
- 1
- 2
example: 0
consumptionState:
type: integer
description: The consumption state of the in-app product. 0 = Yet to be consumed, 1 = Consumed.
enum:
- 0
- 1
example: 0
developerPayload:
type: string
description: Developer-specified string for additional transaction information.
deprecated: true
example: example_value
orderId:
type: string
description: The order ID associated with the purchase.
example: '500123'
purchaseType:
type: integer
description: The type of purchase. 0 = Test (sandbox), 1 = Promo, 2 = Rewarded.
enum:
- 0
- 1
- 2
example: 0
acknowledgementState:
type: integer
description: The acknowledgement state of the in-app product. 0 = Yet to be acknowledged, 1 = Acknowledged.
enum:
- 0
- 1
example: 0
purchaseToken:
type: string
description: The purchase token generated at the time of purchase.
example: example_value
productId:
type: string
description: The in-app product SKU.
example: '500123'
quantity:
type: integer
description: The quantity associated with the purchase.
example: 10
obfuscatedExternalAccountId:
type: string
description: An obfuscated version of the ID uniquely associated with the user's account in your app.
example: '500123'
obfuscatedExternalProfileId:
type: string
description: An obfuscated version of the ID uniquely associated with the user's profile in your app.
example: '500123'
regionCode:
type: string
description: ISO 3166-1 alpha-2 billing region code of the user.
example: example_value
refundableQuantity:
type: integer
description: The quantity eligible for refund.
example: 10
SubscriptionPurchasesDeferResponse:
type: object
description: Response from deferring a subscription purchase.
properties:
newExpiryTimeMillis:
type: string
format: int64
description: The new expiry time for the subscription.
example: example_value
SubscriptionPurchase:
type: object
description: Represents a subscription purchase. Contains the subscription state, expiry time, auto-renewal status, and cancellation details.
properties:
kind:
type: string
description: Resource type identifier.
const: androidpublisher#subscriptionPurchase
example: example_value
startTimeMillis:
type: string
format: int64
description: Time at which the subscription was granted (milliseconds since Epoch).
example: example_value
expiryTimeMillis:
type: string
format: int64
description: Time at which the subscription will expire (milliseconds since Epoch). For cancelled subscriptions, this is when access ends.
example: example_value
userCancellationTimeMillis:
type: string
format: int64
description: Time at which the subscription was canceled by the user (milliseconds since Epoch). Only present if cancelReason is 0.
example: example_value
autoRenewing:
type: boolean
description: Whether the subscription will automatically be renewed.
example: true
priceCurrencyCode:
type: string
description: ISO 4217 currency code for the subscription price.
example: example_value
priceAmountMicros:
type: string
format: int64
description: Price of the subscription in micro-units of the currency. For example, 7990000 represents $7.99.
example: example_value
introductoryPriceInfo:
$ref: '#/components/schemas/IntroductoryPriceInfo'
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code of the user at the time the subscription was granted.
example: example_value
developerPayload:
type: string
description: Developer-specified string for additional information.
deprecated: true
example: example_value
paymentState:
type: integer
description: The payment state of the subscription. 0 = Payment pending, 1 = Payment received, 2 = Free trial, 3 = Pending deferred upgrade/downgrade.
enum:
- 0
- 1
- 2
- 3
example: 0
cancelReason:
type: integer
description: The reason a subscription was cancelled or not auto-renewed. 0 = User cancelled, 1 = System cancelled (billing issue), 2 = Replaced with a new subscription, 3 = Developer cancelled.
enum:
- 0
- 1
- 2
- 3
example: 0
linkedPurchaseToken:
type: string
description: The purchase token of the previous subscription if this subscription is a replacement (upgrade/downgrade).
example: example_value
purchaseType:
type: integer
description: The type of purchase. 0 = Test (sandbox), 1 = Promo.
enum:
- 0
- 1
example: 0
orderId:
type: string
description: The order ID of the latest recurring order.
example: '500123'
acknowledgementState:
type: integer
description: The acknowledgement state. 0 = Yet to be acknowledged, 1 = Acknowledged.
enum:
- 0
- 1
example: 0
externalAccountId:
type: string
description: User account identifier in the third-party service.
example: '500123'
promotionType:
type: integer
description: The type of promotion applied on this purchase. 0 = One-time code, 1 = Vanity code.
enum:
- 0
- 1
example: 0
promotionCode:
type: string
description: The promotion code applied on this purchase.
example: example_value
obfuscatedExternalAccountId:
type: string
description: Obfuscated user account ID in the third-party service.
example: '500123'
obfuscatedExternalProfileId:
type: string
description: Obfuscated user profile ID in the third-party service.
example: '500123'
VoidedPurchase:
type: object
description: A purchase that has been voided (cancelled, refunded, or charged back).
properties:
kind:
type: string
description: Resource type identifier.
const: androidpublisher#voidedPurchase
example: example_value
purchaseToken:
type: string
description: The token which uniquely identifies the purchase.
example: example_value
purchaseTimeMillis:
type: string
format: int64
description: Time at which the purchase was made (milliseconds since Epoch).
example: example_value
voidedTimeMillis:
type: string
format: int64
description: Time at which the purchase was voided (milliseconds since Epoch).
example: example_value
orderId:
type: string
description: The order ID associated with the voided purchase.
example: '500123'
voidedSource:
type: integer
description: The source of the voiding. 0 = User, 1 = Developer, 2 = Google.
enum:
- 0
- 1
- 2
example: 0
voidedReason:
type: integer
description: The reason for voiding. 0 = Other, 1 = Remorse, 2 = Not received, 3 = Defective, 4 = Accidental purchase, 5 = Fraud, 6 = Friendly fraud, 7 = Chargeback.
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
example: 0
voidedQuantity:
type: integer
description: The voided quantity as related t
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/android/refs/heads/main/openapi/android-purchases-api-openapi.yml