$gpc purchases

--json

Manage purchases, subscription purchases, voided purchases, and order refunds.

usagegpc purchases <subcommand> [options]

Commands

Command	Description
purchases get	Get a product purchase
purchases acknowledge	Acknowledge a product purchase
purchases consume	Consume a consumable purchase
purchases subscription get	Get a subscription purchase (v2 API)
purchases subscription cancel	Cancel a subscription (v1 API)
purchases subscription defer	Defer a subscription expiry
purchases subscription revoke	Revoke a subscription (v2 API)
purchases product get-v2	Get product purchase (v2 — multi-offer OTPs)
purchases subscription cancel-v2	Cancel a subscription (v2 — cancellation types)
purchases subscription defer-v2	Defer subscription renewal (v2 — add-ons)
purchases voided	List voided purchases
purchases orders get	Get order details
purchases orders batch-get	Batch get orders (up to 1000)
purchases orders refund	Refund an order

purchases get

Get product purchase details using both v1 and v2 API endpoints.

Synopsis

gpc purchases get <product-id> <token>

Options

No command-specific options.

Example

gpc purchases get coins_100 "purchase-token-abc123" \
  --app com.example.myapp

{
  "purchaseState": 0,
  "consumptionState": 0,
  "developerPayload": "",
  "orderId": "GPA.1234-5678-9012-34567",
  "purchaseType": 0,
  "acknowledgementState": 1,
  "purchaseTimeMillis": "1741046400000",
  "regionCode": "US"
}

---

purchases acknowledge

Acknowledge a product purchase. Required for all purchases to prevent automatic refund after 3 days.

Synopsis

gpc purchases acknowledge <product-id> <token> [options]

Options

Flag	Short	Type	Default	Description
--payload		string		Developer payload string

Example

gpc purchases acknowledge coins_100 "purchase-token-abc123" \
  --app com.example.myapp

With developer payload:

gpc purchases acknowledge coins_100 "purchase-token-abc123" \
  --app com.example.myapp \
  --payload "user_id=12345"

Preview without acknowledging:

gpc purchases acknowledge coins_100 "purchase-token-abc123" \
  --app com.example.myapp \
  --dry-run

---

purchases consume

Consume a consumable product purchase, allowing the user to buy it again.

Synopsis

gpc purchases consume <product-id> <token>

Options

No command-specific options.

Example

gpc purchases consume coins_100 "purchase-token-abc123" \
  --app com.example.myapp

---

purchases subscription get

Get subscription purchase details using the v2 Purchases API.

Synopsis

gpc purchases subscription get <token>

Options

No command-specific options.

Example

gpc purchases subscription get "sub-token-xyz789" \
  --app com.example.myapp

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "lineItems": [
    {
      "productId": "premium_monthly",
      "expiryTime": "2026-04-09T12:00:00Z",
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "regionCode": "US"
}

Subscription Recovery (I/O 2026)

Google extended the account recovery window from 30 to 60 days for failed payments. Top developers reported up to 18% reduction in involuntary churn.

Two new fields on SubscriptionPurchaseV2 (added in GPC v0.9.76) give visibility into payment failures:

• onHoldStateContext -- present when subscriptionState is SUBSCRIPTION_STATE_ON_HOLD. Contains renewalDeclined.pendingOrderId from the declined renewal.
• inGracePeriodStateContext -- present when subscriptionState is SUBSCRIPTION_STATE_IN_GRACE_PERIOD. Contains renewalDeclined.pendingOrderId during the retry window.

GPC v0.9.79 also surfaces two top-level convenience fields so you do not need to drill into the state context objects:

• onHoldPendingOrderId -- the pending order ID when the subscription is on hold.
• gracePeriodPendingOrderId -- the pending order ID when the subscription is in grace period.

A new delayed charging optimization lets low-risk users keep access while payment retries happen in the background. No GPC configuration changes needed.

---

purchases subscription cancel

Cancel an active subscription. The subscription remains active until the end of the current billing period.

Synopsis

gpc purchases subscription cancel <subscription-id> <token>

Options

No command-specific options.

Example

gpc purchases subscription cancel premium_monthly "sub-token-xyz789" \
  --app com.example.myapp

---

purchases subscription defer

Defer a subscription's expiry date to a later time.

Synopsis

gpc purchases subscription defer <subscription-id> <token> --expiry <iso-date>

Options

Flag	Short	Type	Default	Description
--expiry		string	(required)	Desired new expiry date (ISO 8601)

Example

gpc purchases subscription defer premium_monthly "sub-token-xyz789" \
  --app com.example.myapp \
  --expiry 2026-06-01T00:00:00Z

{
  "newExpiryTimeMillis": "1748736000000"
}

---

purchases subscription revoke

Revoke a subscription immediately using the v2 API. The user loses access right away.

Synopsis

gpc purchases subscription revoke <token>

Options

No command-specific options.

Example

gpc purchases subscription revoke "sub-token-xyz789" \
  --app com.example.myapp

---

purchases voided

List voided purchases (refunds, chargebacks, revocations).

Synopsis

gpc purchases voided [options]

Options

Flag	Short	Type	Default	Description
--start-time		string		Start time in milliseconds since epoch
--end-time		string		End time in milliseconds since epoch
--type		number	0	Purchase type: 0 = in-app only, 1 = in-app + subscriptions
--include-partial-refunds		flag		Include quantity-based partial refunds
--max-results		number		Maximum results per page
--limit		number		Maximum total results
--next-page		string		Resume from pagination token

Rate Limit

The voided purchases API is limited to 6,000 requests per day and 30 requests per 30 seconds.

Example

List all voided purchases:

gpc purchases voided --app com.example.myapp

List voided purchases in a time range:

gpc purchases voided \
  --app com.example.myapp \
  --start-time 1709251200000 \
  --end-time 1741046400000 \
  --max-results 50

List output shape (v0.9.83+)

purchases voided --json returns a JSON envelope: voidedPurchases, a nextPageToken (null when there are no more pages), a meta.count, and a message when empty. Switch jq '.[]' to jq '.voidedPurchases[]'.

---

purchases orders refund

Refund an order by order ID.

Synopsis

gpc purchases orders refund <order-id> [options]

Options

Flag	Short	Type	Default	Description
--full-refund		boolean	false	Issue a full refund
--prorated-refund		boolean	false	Issue a prorated refund

Example

Full refund:

gpc purchases orders refund "GPA.1234-5678-9012-34567" \
  --app com.example.myapp \
  --full-refund

Prorated refund:

gpc purchases orders refund "GPA.1234-5678-9012-34567" \
  --app com.example.myapp \
  --prorated-refund

Preview without executing:

gpc purchases orders refund "GPA.1234-5678-9012-34567" \
  --app com.example.myapp \
  --full-refund \
  --dry-run

purchases product get-v2

Get product purchase details using the v2 API. Supports multi-offer one-time products.

Synopsis

gpc purchases product get-v2 <token> [options]

Example

gpc purchases product get-v2 "purchase-token-abc" --app com.example.myapp

---

purchases subscription cancel-v2

Cancel a subscription using the v2 API. Supports cancellation type parameter.

Synopsis

gpc purchases subscription cancel-v2 <token> [options]

Options

Flag	Type	Description
--type	string	Cancellation type: USER_CANCELED, SYSTEM_CANCELED, DEVELOPER_CANCELED, REPLACED

Example

gpc purchases subscription cancel-v2 "purchase-token-abc" \
  --type DEVELOPER_CANCELED \
  --app com.example.myapp

TIP

The v1 cancel command requires both subscription-id and token. The v2 cancel-v2 only requires the token and supports cancellation types.

---

purchases subscription defer-v2

Defer a subscription renewal using the v2 API. Supports subscriptions with add-ons.

Synopsis

gpc purchases subscription defer-v2 <token> --until <date> [options]

Options

Flag	Type	Required	Description
--until	string	Yes	Desired expiry time (ISO 8601 date)

Example

gpc purchases subscription defer-v2 "purchase-token-abc" \
  --until 2026-07-01T00:00:00Z \
  --app com.example.myapp

---

purchases orders get

Get order details by order ID.

Synopsis

gpc purchases orders get <order-id> [options]

Example

gpc purchases orders get "GPA.1234-5678-9012-34567" --app com.example.myapp

---

purchases orders batch-get

Retrieve multiple orders in a single request (up to 1000 order IDs).

Synopsis

gpc purchases orders batch-get --ids <order-ids> [options]

Options

Flag	Type	Required	Description
--ids	string	Yes	Comma-separated order IDs (max 1000)

Example

gpc purchases orders batch-get \
  --ids "GPA.1234,GPA.5678,GPA.9012" \
  --app com.example.myapp \
  --output json

---

Related

• subscriptions -- Subscription product management
• one-time-products -- One-time product management (alias: otp)
• iap -- Legacy in-app product management
• external-transactions -- Alternative billing transactions
• reports -- Financial reports