目录

Data Types

PurchaseOrderPayload

Purchase data model, which supports consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions.

Parameter Mandatory Type Description
environment Yes String

Environment type.

- NORMAL: normal environment.

- SANDBOX: sandbox environment.
purchaseOrderId Yes String Order ID of a purchase. The value contains a maximum of 256 characters.
purchaseToken Yes String Purchase token. In a consumable/non-consumable/non-renewable subscription purchase, each purchase token matches a specific order. In an auto-renewable subscription purchase, each purchase token matches a subscription ID. Each purchase token is valid for only one delivery. To avoid duplicate deliveries to the same user, it is necessary to restrict the number of times a purchase token can be used for delivery. The value contains a maximum of 256 characters.
applicationId Yes String App ID. For details about how to obtain the app ID, please refer to Configuring App Identity Information.
productId Yes String Product ID.
productType Yes String

Product type. The options are as follows:

0: consumable.

1: non-consumable.

2: auto-renewable subscription.

3: non-renewable subscription.
quantity No Long

Number of purchased products. This parameter applies only to batch purchase of consumables and non-renewable subscriptions.

The maximum quantity is 10.

Note: If the quantity parameter is used to support bulk purchases of products, your app needs to verify that the ordered quantity matches the final delivered quantity to prevent under-deliveries or over-deliveries.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

Since: 5.0.3(15)
purchaseTime Yes Long

Purchase time, which is a UTC timestamp in milliseconds.

If the purchase is not complete, this parameter is left empty.
finishStatus No String

Delivery status. The options are as follows:

1: The product is delivered.

2: The product is not delivered.
needFinish No Boolean

Whether the delivery should be acknowledged to complete the purchase process. The options are as follows:

- true: Delivery acknowledgement is required.

- false: Delivery acknowledgement is optional.
price Yes Long Price in currency sub-units. The specific sub-unit, like cents, varies by currency.
currency Yes String Currency. For details, please refer to the ISO 4217 standard. For example, CNY, USD, and MYR.
developerPayload No String Information stored on the merchant side, which you pass when calling the purchase API.
purchaseOrderRevocationReasonCode No String

Reason for revoking an order.

0: others.

1: order revoked at the user's request.
revocationTime No Long Time when a purchase order is canceled, which is a UTC timestamp in milliseconds.
offerTypeCode No String

Offer type.

Consumables, non-consumables, and non-renewable subscriptions:

1: promotional offers for specific user groups.

Auto-renewable subscription.

1: introductory offers for new users.

2: promotional offers for specific user groups.

4: win-back offers for at-risk users.
offerId No String Promotional offer ID.
countryCode Yes String Country/region code, which is used to identify the country or region. For details, please refer to the ISO 3166 standard.
signedTime Yes Long Time when signing is performed, which is a UTC timestamp in milliseconds.

Parameters returned only for auto-renewable subscriptions.

Parameter Mandatory Type Description
subGroupGenerationId Yes String

Subscription group generation ID.

- This ID remains unchanged when a user switches between different subscription products in the same group.

- This ID will change when a user purchases a subscription again after the subscription expires and the account hold period ends.
subscriptionId Yes String

Subscription ID. The ID will change when:

- A user switches from a subscription to another.

- When a user purchases a subscription again after the subscription expires and the account hold period ends.
subGroupId Yes String ID of the subscription group to which a subscription belongs.
duration Yes String Validity period of the current purchase, in ISO 8601 format. For example, P1W represents one week, and P1M represents one month.
durationTypeCode Yes String

Type of a subscription cycle.

0: normal.

1: extended.

PurchaseReservedInfo

Additional information for a purchase promotion.

Parameter Mandatory Type Description
productItem Yes ProductItem Product information.
offerInfo Yes OfferInfo Promotional offer parameter.

ProductItem

Product information.

Parameter Mandatory Type Description
applicationId Yes String App ID. For details about how to obtain the app ID, please refer to Configuring App Identity Information.
productId Yes String Product ID.

OfferInfo

Promotional offer parameter.

Parameter Mandatory Type Description
offerId Yes String Promotional offer ID. This ID comes from promotional information that you have configured in AppGallery Connect. For details, please refer to Setting Promotional Prices.
applicationUserName No String Obfuscated string that uniquely identifies a user's account. This parameter can be provided when a promotional offer ID is included. If this parameter is passed, the same applicationUserName must also be included in PurchaseParameter.
nonce Yes String A lowercase UUID generated by yourself and guaranteed to be system-wide unique.