Create, manage, and query subscription products and their base plans, offers, and purchase entitlements.
openapi: 3.1.0
info:
title: Google Play Developer Orders Subscriptions 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: Subscriptions
description: Create, manage, and query subscription products and their base plans, offers, and purchase entitlements.
externalDocs:
url: https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions
paths:
/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:
- Subscriptions
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:
- Subscriptions
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:
- Subscriptions
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:
- Subscriptions
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:
- Subscriptions
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:
- Subscriptions
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}/monetization/subscriptions:
get:
operationId: listSubscriptions
summary: List Subscription Products
description: Lists all subscriptions defined for the specified application. Returns subscription metadata including product IDs, listings, and base plans.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- name: pageSize
in: query
description: Maximum number of subscriptions to return.
schema:
type: integer
maximum: 100
example: 10
- name: pageToken
in: query
description: Page token for pagination.
schema:
type: string
example: example_value
- name: showArchived
in: query
description: Whether to include archived subscriptions in the response.
schema:
type: boolean
example: true
responses:
'200':
description: Successful response with list of subscriptions
content:
application/json:
schema:
$ref: '#/components/schemas/ListSubscriptionsResponse'
examples:
Listsubscriptions200Example:
summary: Default listSubscriptions 200 response
x-microcks-default: true
value:
subscriptions:
- packageName: example_value
productId: '500123'
basePlans: {}
listings: {}
archived: true
nextPageToken: example_value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createSubscription
summary: Create a Subscription Product
description: Creates a new subscription for an application. The subscription must include at least one base plan and listing.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- name: productId
in: query
required: true
description: The ID to use for the subscription. Must be unique within the app.
schema:
type: string
example: '500123'
- name: regionsVersion.version
in: query
description: The version of the available regions being used.
schema:
type: string
example: example_value
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
CreatesubscriptionRequestExample:
summary: Default createSubscription request
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlans:
- basePlanId: '500123'
state: STATE_UNSPECIFIED
regionalConfigs: {}
autoRenewingBasePlanType: {}
prepaidBasePlanType: {}
offerTags: {}
listings:
- languageCode: example_value
title: Example Title
benefits: {}
description: A sample description.
archived: true
taxAndComplianceSettings:
eeaWithdrawalRightType: WITHDRAWAL_RIGHT_TYPE_UNSPECIFIED
taxRateInfoByRegionCode: example_value
isTokenizedDigitalAsset: true
responses:
'200':
description: Subscription created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
Createsubscription200Example:
summary: Default createSubscription 200 response
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlans:
- basePlanId: '500123'
state: STATE_UNSPECIFIED
regionalConfigs: {}
autoRenewingBasePlanType: {}
prepaidBasePlanType: {}
offerTags: {}
listings:
- languageCode: example_value
title: Example Title
benefits: {}
description: A sample description.
archived: true
taxAndComplianceSettings:
eeaWithdrawalRightType: WITHDRAWAL_RIGHT_TYPE_UNSPECIFIED
taxRateInfoByRegionCode: example_value
isTokenizedDigitalAsset: true
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: Conflict - subscription with this ID already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/monetization/subscriptions/{productId}:
get:
operationId: getSubscription
summary: Get a Subscription Product
description: Reads a single subscription product configuration, including its base plans, offers, and regional pricing.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
responses:
'200':
description: Successful response with subscription details
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
Getsubscription200Example:
summary: Default getSubscription 200 response
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlans:
- basePlanId: '500123'
state: STATE_UNSPECIFIED
regionalConfigs: {}
autoRenewingBasePlanType: {}
prepaidBasePlanType: {}
offerTags: {}
listings:
- languageCode: example_value
title: Example Title
benefits: {}
description: A sample description.
archived: true
taxAndComplianceSettings:
eeaWithdrawalRightType: WITHDRAWAL_RIGHT_TYPE_UNSPECIFIED
taxRateInfoByRegionCode: example_value
isTokenizedDigitalAsset: true
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateSubscription
summary: Update a Subscription Product
description: Updates an existing subscription product configuration. Supports partial updates via the updateMask field.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- name: updateMask
in: query
description: The list of fields to update in this subscription. Uses FieldMask format.
schema:
type: string
example: example_value
- name: regionsVersion.version
in: query
description: The version of the available regions being used.
schema:
type: string
example: example_value
- name: latencyTolerance
in: query
description: Tolerance for propagation latency. PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_SENSITIVE or PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT.
schema:
type: string
enum:
- PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_SENSITIVE
- PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
example: PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_SENSITIVE
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
UpdatesubscriptionRequestExample:
summary: Default updateSubscription request
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlans:
- basePlanId: '500123'
state: STATE_UNSPECIFIED
regionalConfigs: {}
autoRenewingBasePlanType: {}
prepaidBasePlanType: {}
offerTags: {}
listings:
- languageCode: example_value
title: Example Title
benefits: {}
description: A sample description.
archived: true
taxAndComplianceSettings:
eeaWithdrawalRightType: WITHDRAWAL_RIGHT_TYPE_UNSPECIFIED
taxRateInfoByRegionCode: example_value
isTokenizedDigitalAsset: true
responses:
'200':
description: Subscription updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
Updatesubscription200Example:
summary: Default updateSubscription 200 response
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlans:
- basePlanId: '500123'
state: STATE_UNSPECIFIED
regionalConfigs: {}
autoRenewingBasePlanType: {}
prepaidBasePlanType: {}
offerTags: {}
listings:
- languageCode: example_value
title: Example Title
benefits: {}
description: A sample description.
archived: true
taxAndComplianceSettings:
eeaWithdrawalRightType: WITHDRAWAL_RIGHT_TYPE_UNSPECIFIED
taxRateInfoByRegionCode: example_value
isTokenizedDigitalAsset: true
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSubscription
summary: Delete a Subscription Product
description: Deletes a subscription. A subscription can only be deleted if it has never had a base plan published.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
responses:
'204':
description: Subscription deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/applications/{packageName}/monetization/subscriptions/{productId}/basePlans/{basePlanId}/offers:
get:
operationId: listSubscriptionOffers
summary: List Subscription Offers
description: Lists all offers for a given subscription's base plan. Returns offer details including eligibility criteria and pricing phases.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/basePlanId'
- name: pageSize
in: query
description: Maximum number of offers to return.
schema:
type: integer
example: 10
- name: pageToken
in: query
description: Page token for pagination.
schema:
type: string
example: example_value
responses:
'200':
description: Successful response with list of subscription offers
content:
application/json:
schema:
$ref: '#/components/schemas/ListSubscriptionOffersResponse'
examples:
Listsubscriptionoffers200Example:
summary: Default listSubscriptionOffers 200 response
x-microcks-default: true
value:
subscriptionOffers:
- packageName: example_value
productId: '500123'
basePlanId: '500123'
offerId: '500123'
state: STATE_UNSPECIFIED
phases: {}
targeting: {}
regionalConfigs: {}
offerTags: {}
nextPageToken: example_value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createSubscriptionOffer
summary: Create a Subscription Offer
description: Creates a new subscription offer. An offer represents special pricing or a free trial for a base plan.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/packageName'
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/basePlanId'
- name: offerId
in: query
required: true
description: The ID to use for the offer. Must be unique within the base plan.
schema:
type: string
example: '500123'
- name: regionsVersion.version
in: query
description: The version of the available regions being used.
schema:
type: string
example: example_value
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionOffer'
examples:
CreatesubscriptionofferRequestExample:
summary: Default createSubscriptionOffer request
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlanId: '500123'
offerId: '500123'
state: STATE_UNSPECIFIED
phases:
- recurrenceCount: 10
duration: example_value
regionalConfigs: {}
targeting:
acquisitionRule:
scope:
anySubscriptionInApp: example_value
specificSubscriptionInApp: example_value
upgradeRule:
billingPeriodDuration: example_value
oncePerUser: true
regionalConfigs:
- regionCode: example_value
newSubscriberAvailability: true
offerTags:
- tag: example_value
responses:
'200':
description: Subscription offer created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionOffer'
examples:
Createsubscriptionoffer200Example:
summary: Default createSubscriptionOffer 200 response
x-microcks-default: true
value:
packageName: example_value
productId: '500123'
basePlanId: '500123'
offerId: '500123'
state: STATE_UNSPECIFIED
phases:
- recurrenceCount: 10
duration: example_value
regionalConfigs: {}
targeting:
acquisitionRule:
scope:
anySubscriptionInApp: example_value
specificSubscriptionInApp: example_value
upgradeRule:
billingPeriodDuration: example_value
oncePerUser: true
regionalConfigs:
- regionCode: example_value
newSubscriberAvailability: true
offerTags:
- tag: example_value
'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
basePlanId:
name: basePlanId
in: path
required: true
description: The unique identifier of the base plan. Base plans define the billing period and renewal type for a subscription.
schema:
type: string
example: monthly
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:
ListSubscriptionOffersResponse:
type: object
description: Response containing a list of subscription offers.
properties:
subscriptionOffers:
type: array
items:
$ref: '#/components/schemas/SubscriptionOffer'
example: []
nextPageToken:
type: string
description: Token for the next page of results.
example: example_value
ListSubscriptionsResponse:
type: object
description: Response containing a list of subscriptions.
properties:
subscriptions:
type: array
items:
$ref: '#/components/schemas/Subscription'
example: []
nextPageToken:
type: string
description: Token for the next page of results.
example: example_value
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
SubscriptionOffer:
type: object
description: A subscription offer represents special pricing for a subscription, such as a free trial or introductory price.
properties:
packageName:
type: string
description: The package name of the parent app.
readOnly: true
example: example_value
productId:
type: string
description: The product ID of the parent subscription.
readOnly: true
example: '500123'
basePlanId:
type: string
description: The base plan ID the offer is associated with.
readOnly: true
example: '500123'
offerId:
type: string
description: The unique identifier for this offer.
readOnly: true
example: '500123'
state:
type: string
description: The current state of the offer.
enum:
- STATE_UNSPECIFIED
- DRAFT
- ACTIVE
- INACTIVE
readOnly: true
example: STATE_UNSPECIFIED
phases:
type: array
description: The pricing phases for this of
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/android/refs/heads/main/openapi/android-subscriptions-api-openapi.yml