Package google.cloud.payments.reseller.subscription.v1

Index

PaymentsResellerOutboundService

Service allowing Google to make outbound calls to partners to authorize subscription and purchase order changes.

AuthorizePurchaseOrderCharge

rpc AuthorizePurchaseOrderCharge(AuthorizePurchaseOrderChargeRequest) returns (AuthorizePurchaseOrderChargeResponse)

Used by Google to check with reseller whether a charge for purchase order is authorized. If the purchase order is originated from a subscription, declining the charge will also cancel the originating subscription, or deactivate the originating subscription line items.

Note: The domain name should be replaced with the partner domain name with same path as here.

AuthorizeSubscriptionAddon

rpc AuthorizeSubscriptionAddon(AuthorizeSubscriptionAddonRequest) returns (AuthorizeSubscriptionAddonResponse)

Used by Google to check with reseller whether an add-on to the subscription is authorized.

Note: The domain name should be replaced with the partner domain name with same path as here.

AuthorizeSubscriptionSignup

rpc AuthorizeSubscriptionSignup(AuthorizeSubscriptionSignupRequest) returns (AuthorizeSubscriptionSignupResponse)

Used by Google to check with reseller whether the subscription signup is authorized.

Note: The domain name should be replaced with the partner domain name with same path as here.

PaymentsResellerSubscriptionService

Service allowing partners to create and manage subscriptions for their customers.

CancelSubscription

rpc CancelSubscription(CancelSubscriptionRequest) returns (CancelSubscriptionResponse)

Used by partners to cancel a subscription service either immediately or by the end of the current billing cycle for their customers. It should be called directly by the partner using service accounts.

CreateSubscription

rpc CreateSubscription(CreateSubscriptionRequest) returns (Subscription)

Used by partners to create a subscription for their customers. The created subscription is associated with the end user inferred from the end user credentials. This API must be authorized by the end user using OAuth.

EntitleSubscription

rpc EntitleSubscription(EntitleSubscriptionRequest) returns (EntitleSubscriptionResponse)

Used by partners to entitle a previously provisioned subscription to the current end user. The end user identity is inferred from the authorized credential of the request. This API must be authorized by the end user using OAuth.

ExtendSubscription

rpc ExtendSubscription(ExtendSubscriptionRequest) returns (ExtendSubscriptionResponse)

[Opt-in only] Most partners should be on auto-extend by default. Used by partners to extend a subscription service for their customers on an ongoing basis for the subscription to remain active and renewable. It should be called directly by the partner using service accounts.

FindEligiblePromotions

rpc FindEligiblePromotions(FindEligiblePromotionsRequest) returns (FindEligiblePromotionsResponse)

To find eligible promotions for the current user. The API requires user authorization via OAuth. The bare minimum oauth scope openid is sufficient, which will skip the consent screen.

GenerateUserSession

rpc GenerateUserSession(GenerateUserSessionRequest) returns (GenerateUserSessionResponse)

[Preview only]. This API replaces user authorized OAuth based APIs (Create and Entitle). Preview APIs are working in progress and are subject to change. Generates a token for a short-lived user session based on the user intent. The session token can be used to redirect the user to Google to finish the signup flow. The session token is valid for 1 hour.

GetSubscription

rpc GetSubscription(GetSubscriptionRequest) returns (Subscription)

Used by partners to get a subscription by id. It should be called directly by the partner using service accounts.

ListProducts

rpc ListProducts(ListProductsRequest) returns (ListProductsResponse)

To retrieve the products that can be resold by the partner. It should be autenticated with a service account.

  • This API doesn't apply to YouTube products currently.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

Retrieves the promotions, such as free trial, that can be used by the partner.

  • This API doesn't apply to YouTube promotions currently.

It should be autenticated with a service account.

ProvisionSubscription

rpc ProvisionSubscription(ProvisionSubscriptionRequest) returns (Subscription)

Used by partners to provision a subscription for their customers. This creates a subscription without associating it with the end user account. EntitleSubscription must be called separately using OAuth in order for the end user account to be associated with the subscription. It should be called directly by the partner using service accounts.

UndoCancelSubscription

rpc UndoCancelSubscription(UndoCancelSubscriptionRequest) returns (UndoCancelSubscriptionResponse)

Revokes the pending cancellation of a subscription, which is currently in STATE_CANCEL_AT_END_OF_CYCLE state. If the subscription is already cancelled, the request will fail.

  • This API doesn't apply to YouTube subscriptions.

It should be called directly by the partner using service accounts.

Amount

Describes the amount unit including the currency code.

Fields
currency_code

string

Required. Currency codes in accordance with ISO-4217 Currency Codes. For example, USD.

amount_micros

int64

Required. Amount in micros (1_000_000 micros = 1 currency unit)

AuthorizationResult

The set of potential responses the reseller can give for actions like purchase order charge, subscription signup and add-on etc.

Enums
AUTHORIZATION_RESULT_UNSPECIFIED Unspecified. It is reserved as an invalid value. Do not use.
AUTHORIZATION_RESULT_AUTHORIZED The reseller authorized the action.
AUTHORIZATION_RESULT_REJECTED The reseller rejected the action.

AuthorizePurchaseOrderChargeRequest

The reseller to authorize a charge for a purchase order.

Fields
parent

string

Required. The parent resource name, which is the identifier of the partner. It will have the format of "partners/{partner_id}".

request_id

string

Required. A random UUID to uniquely identify the request. The idempotency key for the request. So in case of retries, request_id will be same as previous one.

purchase_order

PurchaseOrder

Required. Details of the charge.

AuthorizePurchaseOrderChargeResponse

The reseller's determination as to whether the charge should be approved.

Fields
authorization_result

AuthorizationResult

Required. The reseller's authorization result for purchase order charge request.

purchase_order_id

string

Required. Sets the id only if the authorization is approved. The id assigned by the partner for the authorized purchase order. The purchase order notification from Cloud pubsub notification message will contain the resource name with this id.

AuthorizeSubscriptionAddonRequest

The reseller to authorize an add-on for a subscription.

Fields
name

string

Required. The name of the subscription resource for which addon is being requested. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

request_id

string

Required. A UUID to uniquely identify the request. The idempotency key for the request. So in case of retries, request_id will be same as previous one.

subscription

Subscription

Required. Details of the subscription for add-on request.

new_line_items[]

LineItem

Required. Details of the new line items that are being added to the subscription.

AuthorizeSubscriptionAddonResponse

The reseller's determination as to whether an add-on to the subscription should be approved.

Fields
authorization_result

AuthorizationResult

Required. The reseller's authorization result for subscription add-on request.

AuthorizeSubscriptionSignupRequest

The reseller to authorize a subscription signup.

Fields
parent

string

Required. The parent resource name, which is the identifier of the partner. It will have the format of "partners/{partner_id}".

request_id

string

Required. A random UUID to uniquely identify the request. The idempotency key for the request. So in case of retries, request_id will be same as previous one.

subscription

Subscription

Required. Details of the subscription signup.

AuthorizeSubscriptionSignupResponse

The reseller's determination as to whether the subscription signup should be approved.

Fields
authorization_result

AuthorizationResult

Required. The reseller's authorization result for subscription signup request.

subscription_id

string

Sets the id only if the authorization is approved. The id assigned by the partner for the authorized subscription. The subscription notification from Cloud pubsub notification message will contain the resource name with this id.

CancelSubscriptionRequest

Request to cancel a subscription.

Fields
name

string

Required. The name of the subscription resource to be cancelled. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

cancellation_reason

CancellationReason

Specifies the reason for the cancellation.

cancel_immediately

bool

Optional. If true, Google will cancel the subscription immediately, and may or may not (based on the contract) issue a prorated refund for the remainder of the billing cycle. Otherwise, Google defers the cancelation at renewal_time, and will not issue a refund.

  • YouTube subscriptions must use this option currently. However, the user will still have access to the subscription until the end of the billing cycle.

CancelSubscriptionResponse

Response that contains the cancelled subscription resource.

Fields
subscription

Subscription

The cancelled subscription resource.

CancellationReason

Describes the reason for cancellation of the subscription.

Enums
CANCELLATION_REASON_UNSPECIFIED Reason is unspecified. Should not be used.
CANCELLATION_REASON_FRAUD Fraudualant transaction.
CANCELLATION_REASON_REMORSE Buyer's remorse.
CANCELLATION_REASON_ACCIDENTAL_PURCHASE Accidential purchase.
CANCELLATION_REASON_PAST_DUE Payment is past due.
CANCELLATION_REASON_ACCOUNT_CLOSED Used for notification only, do not use in Cancel API. User account closed.
CANCELLATION_REASON_UPGRADE_DOWNGRADE Used for notification only, do not use in Cancel API. Cancellation due to upgrade or downgrade.
CANCELLATION_REASON_USER_DELINQUENCY Cancellation due to user delinquency
CANCELLATION_REASON_SYSTEM_ERROR Used for notification only, do not use in Cancel API. Cancellation due to an unrecoverable system error.
CANCELLATION_REASON_SYSTEM_CANCEL Used for notification only, do not use in Cancel API. The subscription is cancelled by Google automatically since it is no longer valid.
CANCELLATION_REASON_OTHER Other reason.

CreateSubscriptionRequest

Request message for creating a Subscription resource.

Fields
parent

string

Required. The parent resource name, which is the identifier of the partner. It will have the format of "partners/{partner_id}".

subscription

Subscription

Required. The Subscription to be created.

subscription_id

string

Required. Identifies the subscription resource on the Partner side. The value is restricted to 63 ASCII characters at the maximum. If a subscription was previously created with the same subscription_id, we will directly return that one.

Duration

Describes the length of a period of a time.

Fields
unit

Unit

The unit used for the duration

count

int32

number of duration units to be included.

EntitleSubscriptionRequest

Partner request for entitling the previously provisioned subscription to an end user. The end user identity is inferred from the request OAuth context.

Fields
name

string

Required. The name of the subscription resource that is entitled to the current end user. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

line_item_entitlement_details[]

LineItemEntitlementDetails

Optional. The line items to be entitled. If unspecified, all line items will be entitled.

LineItemEntitlementDetails

The details of the line item to be entitled.

Fields
line_item_index

int32

Required. The index of the line item to be entitled.

products[]

string

Optional. Only applicable if the line item corresponds to a hard bundle. Product resource names that identify the bundle elements to be entitled in the line item. If unspecified, all bundle elements will be entitled. The format is 'partners/{partner_id}/products/{product_id}'.

EntitleSubscriptionResponse

Response that contains the entitled subscription resource.

Fields
subscription

Subscription

The subscription that has user linked to it.

ExtendSubscriptionRequest

Request message for extending a Subscription resource. A new recurrence will be made based on the subscription schedule defined by the original product.

Fields
name

string

Required. The name of the subscription resource to be extended. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}".

request_id

string

Required. Restricted to 36 ASCII characters. A random UUID is recommended. The idempotency key for the request. The ID generation logic is controlled by the partner. request_id should be the same as on retries of the same request. A different request_id must be used for a extension of a different cycle.

extension

Extension

Required. Specifies details of the extension. Currently, the duration of the extension must be exactly one billing cycle of the original subscription.

ExtendSubscriptionResponse

Response that contains the timestamps after the extension.

Fields
cycle_end_time

Timestamp

The time at which the subscription is expected to be extended, in ISO 8061 format. UTC timezone. Example, "cycleEndTime":"2019-08-31T17:28:54.564Z"

renewal_time

Timestamp

Output only. The time at which the subscription is expected to be renewed by Google - a new charge will be incurred and the service entitlement will be renewed. A non-immediate cancellation will take place at this time too, before which, the service entitlement for the end user will remain valid. UTC timezone in ISO 8061 format. For example: "2019-08-31T17:28:54.564Z"

free_trial_end_time

Timestamp

End of the free trial period, in ISO 8061 format. UTC timezone. Example, "freeTrialEndTime":"2019-08-31T17:28:54.564Z" This time will be set the same as initial subscription creation time if no free trial period is offered to the partner.

Extension

Describes the details of an extension request.

Fields
partner_user_token

string

Required. Identifier of the end-user in partner’s system.

duration

Duration

Required. Specifies the period of access the subscription should grant.

FindEligiblePromotionsRequest

Request to find eligible promotions for the current user.

Fields
parent

string

Required. The parent, the partner that can resell. Format: partners/{partner}

filter

string

Optional. Specifies the filters for the promotion results. The syntax is defined in https://google.aip.dev/160 with the following caveats:

  1. Only the following features are supported:
    • Logical operator AND
    • Comparison operator = (no wildcards *)
    • Traversal operator .
    • Has operator : (no wildcards *)
  2. Only the following fields are supported:
    • applicableProducts
    • regionCodes
    • youtubePayload.partnerEligibilityId
    • youtubePayload.postalCode
  3. Unless explicitly mentioned above, other features are not supported. Example:

applicableProducts:partners/partner1/products/product1 AND regionCodes:US AND youtubePayload.postalCode=94043 AND youtubePayload.partnerEligibilityId=eligibility-id

page_size

int32

Optional. The maximum number of promotions to return. The service may return fewer than this value. If unspecified, at most 50 products will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

Optional. A page token, received from a previous ListPromotions call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListPromotions must match the call that provided the page token.

FindEligiblePromotionsResponse

Response containing the found promotions for the current user.

Fields
promotions[]

Promotion

The promotions for the current user.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is empty, there are no subsequent pages.

FiniteBillingCycleDetails

Details for a subscriptiin line item with finite billing cycles.

Fields
billing_cycle_count_limit

int64

Required. The number of a subscription line item billing cycles after which billing will stop automatically.

GenerateUserSessionRequest

[Preview only] Request to generate a user session.

Fields
parent

string

Required. The parent, the partner that can resell. Format: partners/{partner}

intent_payload

IntentPayload

The user intent to generate the user session.

GenerateUserSessionResponse

[Preview only] Response that contains the details for generated user session.

Fields
user_session

UserSession

The generated user session.

GetSubscriptionRequest

Request message for retrieving a Subscription resource.

Fields
name

string

Required. The name of the subscription resource to retrieve. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

GoogleOnePayload

Payload specific to Google One products.

Fields
campaigns[]

string

Campaign attributed to sales of this subscription.

sales_channel

Channel

The type of sales channel through which the subscription was sold.

store_id

string

The identifier for the partner store where the subscription was sold.

offering

Offering

The type of offering the subscription was sold by the partner. e.g. VAS.

Channel

Describes the channel through which the subscription was sold by partner.

Enums
CHANNEL_UNSPECIFIED The channel type is unspecified.
CHANNEL_RETAIL Sold at store.
CHANNEL_ONLINE_WEB Sold through partner website.
CHANNEL_ONLINE_ANDROID_APP Sold through partner android app.
CHANNEL_ONLINE_IOS_APP Sold through partner iOS app.

Offering

Describes the type of partner offering the subscription was part of.

Enums
OFFERING_UNSPECIFIED The type of partner offering is unspecified.
OFFERING_VAS_BUNDLE Google One product purchased as a Value added service in addition to existing partner's products. Customer pays additional amount for Google One product.
OFFERING_VAS_STANDALONE Google One product purchased by itself by customer as a value add service. Customer pays additional amount for Google One product.
OFFERING_HARD_BUNDLE Product purchased as part of a hard bundle where Google One was included with the bundle. Google One pricing is included in the bundle.
OFFERING_SOFT_BUNDLE Purchased as part of a bundle where Google One was provided as an option. Google One pricing is included in the bundle.

IntentPayload

The payload that describes the user intent.

Fields

Union field request.

request can be only one of the following:

create_request

CreateSubscriptionRequest

The request to create a subscription.

entitle_request

EntitleSubscriptionRequest

The request to entitle a subscription.

ListProductsRequest

Request to list products.

Fields
parent

string

Required. The parent, the partner that can resell. Format: partners/{partner}

filter

string

Optional. Specifies the filters for the product results. The syntax is defined in https://google.aip.dev/160 with the following caveats:

  1. Only the following features are supported:
    • Logical operator AND
    • Comparison operator = (no wildcards *)
    • Traversal operator .
    • Has operator : (no wildcards *)
  2. Only the following fields are supported:
    • regionCodes
    • youtubePayload.partnerEligibilityId
    • youtubePayload.postalCode
  3. Unless explicitly mentioned above, other features are not supported. Example:

regionCodes:US AND youtubePayload.postalCode=94043 AND youtubePayload.partnerEligibilityId=eligibility-id

page_size

int32

Optional. The maximum number of products to return. The service may return fewer than this value. If unspecified, at most 50 products will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

Optional. A page token, received from a previous ListProducts call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListProducts must match the call that provided the page token.

ListProductsResponse

Response that contains the products.

Fields
products[]

Product

The products for the specified partner.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is empty, there are no subsequent pages.

ListPromotionsRequest

Request to list promotions of a partner.

Fields
parent

string

Required. The parent, the partner that can resell. Format: partners/{partner}

filter

string

Optional. Specifies the filters for the promotion results. The syntax is defined in https://google.aip.dev/160 with the following caveats:

  1. Only the following features are supported:
    • Logical operator AND
    • Comparison operator = (no wildcards *)
    • Traversal operator .
    • Has operator : (no wildcards *)
  2. Only the following fields are supported:
    • applicableProducts
    • regionCodes
    • youtubePayload.partnerEligibilityId
    • youtubePayload.postalCode
  3. Unless explicitly mentioned above, other features are not supported. Example:

applicableProducts:partners/partner1/products/product1 AND regionCodes:US AND youtubePayload.postalCode=94043 AND youtubePayload.partnerEligibilityId=eligibility-id

page_size

int32

Optional. The maximum number of promotions to return. The service may return fewer than this value. If unspecified, at most 50 products will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

Optional. A page token, received from a previous ListPromotions call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListPromotions must match the call that provided the page token.

ListPromotionsResponse

Response that contains the promotions.

Fields
promotions[]

Promotion

The promotions for the specified partner.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is empty, there are no subsequent pages.

Location

Describes a location of an end user.

Fields
region_code

string

2-letter ISO region code for current content region. Ex. “US” Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1

postal_code

string

The postal code this location refers to. Ex. "94043"

PriceDetails

A wrapper message containing various prices.

Fields
pretax_amount

Amount

Optional. The tax-exclusive amount.

tax_amount

Amount

Optional. The amount of tax to collect.

total_amount

Amount

Optional. The total cost, including tax.

Product

A Product resource that defines a subscription service that can be resold.

Fields
name

string

Identifier. Response only. Resource name of the product. It will have the format of "partners/{partner_id}/products/{product_id}"

titles[]

LocalizedText

Output only. Localized human readable name of the product.

subscription_billing_cycle_duration

Duration

Output only. Specifies the length of the billing cycle of the subscription.

region_codes[]

string

Output only. 2-letter ISO region code where the product is available in. Ex. "US" Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1

price_configs[]

PriceConfig

Output only. Price configs for the product in the available regions.

product_type

ProductType

Output only. Output Only. Specifies the type of the product.

bundle_details

BundleDetails

Output only. Output Only. Specifies the details for a bundle product.

finite_billing_cycle_details

FiniteBillingCycleDetails

Optional. Details for a subscription line item with finite billing cycles. If unset, the line item will be charged indefinitely.

BundleDetails

Details for a bundle product.

Fields
bundle_elements[]

BundleElement

The individual products that are included in the bundle.

entitlement_mode

EntitlementMode

The entitlement mode of the bundle product.

BundleElement

The individual product that is included in the bundle.

Fields
product

string

Required. Output only. Product resource name that identifies the bundle element. The format is 'partners/{partner_id}/products/{product_id}'.

EntitlementMode

The entitlement mode of a bundle product.

Enums
ENTITLEMENT_MODE_UNSPECIFIED Unspecified. It's reserved as an unexpected value, should not be used.
ENTITLEMENT_MODE_FULL All the bundle elements must be fully activated in a single request.
ENTITLEMENT_MODE_INCREMENTAL The bundle elements could be incrementally activated.

PriceConfig

Configs the prices in an available region.

Fields
region_code

string

Output only. 2-letter ISO region code where the product is available in. Ex. "US".

amount

Amount

Output only. The price in the region.

ProductType

The type of product.

Enums
PRODUCT_TYPE_UNSPECIFIED Unspecified. It's reserved as an unexpected value, should not be used.
PRODUCT_TYPE_SUBSCRIPTION The product is a subscription.
PRODUCT_TYPE_BUNDLE_SUBSCRIPTION The product is a bundled subscription plan, which includes multiple subscription elements.

ProductPayload

Specifies product specific payload.

Fields
google_one_payload

GoogleOnePayload

Product-specific payloads. Payload specific to Google One products.

youtube_payload

YoutubePayload

Payload specific to Youtube products.

Promotion

A Promotion resource that defines a promotion for a subscription that can be resold.

Fields
name

string

Identifier. Response only. Resource name of the subscription promotion. It will have the format of "partners/{partner_id}/promotion/{promotion_id}"

titles[]

LocalizedText

Output only. Localized human readable name of the promotion.

free_trial_duration

Duration

Optional. Specifies the duration of the free trial of the subscription when promotion_type is PROMOTION_TYPE_FREE_TRIAL

region_codes[]

string

Output only. 2-letter ISO region code where the promotion is available in. Ex. "US" Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1

applicable_products[]

string

Output only. The product ids this promotion can be applied to.

start_time

Timestamp

Optional. Specifies the start time (inclusive) of the period that the promotion is available in.

end_time

Timestamp

Optional. Specifies the end time (exclusive) of the period that the promotion is available in. If unset, the promotion is available indefinitely.

introductory_pricing_details

IntroductoryPricingDetails

Optional. Specifies the introductory pricing details when the promotion_type is PROMOTION_TYPE_INTRODUCTORY_PRICING.

promotion_type

PromotionType

Output only. Output Only. Specifies the type of the promotion.

IntroductoryPricingDetails

The details of a introductory pricing promotion.

Fields
introductory_pricing_specs[]

IntroductoryPricingSpec

Output only. Specifies the introductory pricing periods.

IntroductoryPricingSpec

The duration of an introductory pricing promotion.

Fields
region_code

string

Output only. 2-letter ISO region code where the product is available in. Ex. "US".

recurrence_count

int32

Output only. Output Only. The duration of an introductory offer in billing cycles.

Union field discount_spec.

discount_spec can be only one of the following:

discount_amount

Amount

Output only. The discount amount. The value is positive.

discount_ratio_micros

int64

Output only. The discount percentage in micros. For example, 50,000 represents 5%.

PromotionType

The type of promotion.

Enums
PROMOTION_TYPE_UNSPECIFIED The promotion type is unspecified.
PROMOTION_TYPE_FREE_TRIAL The promotion is a free trial.
PROMOTION_TYPE_INTRODUCTORY_PRICING The promotion is a reduced introductory pricing.

ProvisionSubscriptionRequest

Request message for provisioning a Subscription resource.

Fields
parent

string

Required. The parent resource name, which is the identifier of the partner. It will have the format of "partners/{partner_id}".

subscription

Subscription

Required. The Subscription to be created.

subscription_id

string

Required. Identifies the subscription resource on the Partner side. The value is restricted to 63 ASCII characters at the maximum. If a subscription was previously created with the same subscription_id, we will directly return that one.

PurchaseOrder

A purchase order resold via a third-party reseller.

Fields
name

string

Output only. Identifier. PurchaseOrder resource name in the format of: "partners/{partner_id}/purchaseorders/{purchase_order_id}"

partner_user_token

string

Required. Identifier of the end-user in partner’s system.

line_items[]

PurchaseOrderLineItem

Required. Purchase order line items.

subscription_details

SubscriptionDetails

Optional. Only populated if this order is related to a subscription, such as renewal or proration.

SubscriptionDetails

Details of the subscription this charge is related to.

Fields
subscription

string

Required. Subscription resource name in the format of: "partners/{partner_id}/subscription/{subscription_id}"

purchase_order_type

PurchaseOrderType

Required. The type of the purchase order.

PurchaseOrderType

The type of the purchase order.

Enums
PURCHASE_ORDER_TYPE_UNSPECIFIED Purchase order type is unspecified.
PURCHASE_ORDER_TYPE_RENEWAL This is a renewal purchase order.
PURCHASE_ORDER_TYPE_PRORATION The is a proration purchase order.
PURCHASE_ORDER_TYPE_ONE_TIME The is a one-time purchase order.
PURCHASE_ORDER_TYPE_OFF_CYCLE_CHARGE The is an off cycle charge purchase order.

PurchaseOrderLineItem

Purchase order line item.

Fields
product

string

Required. Product resource name in the format of partners/{partner_id}/products/{product_id}.

description

string

Required. Description of this line item.

amount

Amount

Required. Line item amount.

service_period

ServicePeriod

Optional. Service period this purchase order line item is being delivered over.

charged_details

UnitLevelDetails

Optional. Details about units that are charged.

refunded_details

UnitLevelDetails

Optional. Details about units that are refunded.

line_item_index

int32

Output only. A unique index of the purchase order line item.

ServicePeriod

A description of what time period or moment in time the product or service is being delivered over.

Fields
start_time

Timestamp

Required. The start time of the service period. Time is inclusive.

end_time

Timestamp

Optional. The end time of the service period. Time is exclusive.

Subscription

A subscription serves as a central billing entity between an external partner and Google. The underlying Google services rely on the subscription state to grant or revoke the user's service entitlement.

It's important to note that the subscription state may not always perfectly align with the user's service entitlement. For example, some Google services may continue providing access to the user until the current billing cycle ends, even if the subscription has been immediately canceled. However, other services may not do the same. To fully understand the specific details, please consult the relevant contract or product policy.

Fields
name

string

Identifier. Resource name of the subscription. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}". This is available for authorizeAddon, but otherwise is response only.

products[]

string

Optional. Deprecated: consider using line_items as the input. Required. Resource name that identifies the purchased products. The format will be 'partners/{partner_id}/products/{product_id}'.

promotions[]

string

Optional. Deprecated: consider using the top-level promotion_specs as the input. Optional. Resource name that identifies one or more promotions that can be applied on the product. A typical promotion for a subscription is Free trial. The format will be 'partners/{partner_id}/promotions/{promotion_id}'.

promotion_specs[]

PromotionSpec

Optional. Subscription-level promotions. Only free trial is supported on this level. It determines the first renewal time of the subscription to be the end of the free trial period. Specify the promotion resource name only when used as input.

partner_user_token

string

Required. Identifier of the end-user in partner’s system. The value is restricted to 63 ASCII characters at the maximum.

service_location

Location

Required. The location that the service is provided as indicated by the partner.

purchase_time

Timestamp

Optional. The timestamp when the user transaction was made with the Partner. Specify for the case of "bundle with choice", and it must be before the provision_time (when the user makes a selection).

upgrade_downgrade_details

UpgradeDowngradeDetails

Optional. Details about the previous subscription that this new subscription upgrades/downgrades from. Only populated if this subscription is an upgrade/downgrade from another subscription.

redirect_uri

string

Output only. The place where partners should redirect the end-user to after creation. This field might also be populated when creation failed. However, Partners should always prepare a default URL to redirect the user in case this field is empty.

create_time

Timestamp

Output only. System generated timestamp when the subscription is created. UTC timezone.

update_time

Timestamp

Output only. System generated timestamp when the subscription is most recently updated. UTC timezone.

cycle_end_time

Timestamp

Output only. The time at which the subscription is expected to be extended, in ISO 8061 format. UTC timezone. For example: "2019-08-31T17:28:54.564Z"

renewal_time

Timestamp

Output only. The time at which the subscription is expected to be renewed by Google - a new charge will be incurred and the service entitlement will be renewed. A non-immediate cancellation will take place at this time too, before which, the service entitlement for the end user will remain valid. UTC timezone in ISO 8061 format. For example: "2019-08-31T17:28:54.564Z"

free_trial_end_time

Timestamp

Output only. End of the free trial period, in ISO 8061 format. For example, "2019-08-31T17:28:54.564Z". It will be set the same as createTime if no free trial promotion is specified.

end_user_entitled

bool

Output only. Indicates if the subscription is entitled to the end user.

state

State

Output only. Describes the state of the subscription. See more details at the lifecycle of a subscription.

processing_state

ProcessingState

Output only. Describes the processing state of the subscription. See more details at the lifecycle of a subscription.

cancellation_details

CancellationDetails

Output only. Describes the details of a cancelled subscription. Only applicable to subscription of state STATE_CANCELLED.

line_items[]

LineItem

Required. The line items of the subscription.

CancellationDetails

Describes the details of a cancelled or cancelling subscription.

Fields
reason

CancellationReason

Output only. The reason of the cancellation.

LineItem

Individual line item definition of a subscription.

Fields
product

string

Required. Product resource name that identifies one the line item The format is 'partners/{partner_id}/products/{product_id}'.

description

string

Output only. Description of this line item.

line_item_promotion_specs[]

PromotionSpec

Optional. The promotions applied on the line item. It can be:

  • an introductory pricing promotion.
  • a free trial promotion. This feature is not enabled. If used, the request will be rejected.

When used as input in Create or Provision API, specify its resource name only.

state

LineItemState

Output only. The state of the line item.

line_item_free_trial_end_time

Timestamp

Output only. The free trial end time will be populated after the line item is successfully processed. End time of the line item free trial period, in ISO 8061 format. For example, "2019-08-31T17:28:54.564Z". It will be set the same as createTime if no free trial promotion is specified.

recurrence_type

LineItemRecurrenceType

Output only. The recurrence type of the line item.

one_time_recurrence_details

OneTimeRecurrenceDetails

Output only. Details only set for a ONE_TIME recurrence line item.

product_payload

ProductPayload

Optional. Product specific payload for this line item.

amount

Amount

Output only. The price of the product/service in this line item. The amount could be the wholesale price, or it can include a cost of sale based on the contract.

bundle_details

BundleDetails

Output only. The bundle details for the line item. Only populated if the line item corresponds to a hard bundle.

finite_billing_cycle_details

FiniteBillingCycleDetails

Optional. Details for a subscription line item with finite billing cycles. If unset, the line item will be charged indefinitely. Used only with LINE_ITEM_RECURRENCE_TYPE_PERIODIC.

line_item_index

int32

Output only. A unique index of the subscription line item.

BundleDetails

The bundle details for a line item corresponding to a hard bundle.

Fields
bundle_element_details[]

BundleElementDetails

Output only. The details for each element in the hard bundle.

BundleElementDetails

The details for an element in the hard bundle.

Fields
product

string

Output only. Product resource name that identifies the bundle element. The format is 'partners/{partner_id}/products/{product_id}'.

user_account_linked_time

Timestamp

Output only. The time when this product is linked to an end user.

LineItemRecurrenceType

The recurrence type of the line item.

Enums
LINE_ITEM_RECURRENCE_TYPE_UNSPECIFIED The line item recurrence type is unspecified.
LINE_ITEM_RECURRENCE_TYPE_PERIODIC The line item recurs periodically.
LINE_ITEM_RECURRENCE_TYPE_ONE_TIME The line item does not recur in the future.

LineItemState

The state of a subscription line item.

Enums
LINE_ITEM_STATE_UNSPECIFIED Unspecified state.
LINE_ITEM_STATE_ACTIVE The line item is in ACTIVE state. If the subscription is cancelled or suspended, the line item will not be charged even if the line item is active.
LINE_ITEM_STATE_INACTIVE The line item is in INACTIVE state.
LINE_ITEM_STATE_NEW The line item is new, and is not activated or charged yet.
LINE_ITEM_STATE_ACTIVATING The line item is being activated in order to be charged. If a free trial applies to the line item, the line item is pending a prorated charge at the end of the free trial period, as indicated by line_item_free_trial_end_time.
LINE_ITEM_STATE_DEACTIVATING The line item is being deactivated, and a prorated refund in being processed.
LINE_ITEM_STATE_WAITING_TO_DEACTIVATE The line item is scheduled to be deactivated at the end of the current cycle.
LINE_ITEM_STATE_OFF_CYCLE_CHARGING Line item is being charged off-cycle.

OneTimeRecurrenceDetails

Details for a ONE_TIME recurrence line item.

Fields
service_period

ServicePeriod

Output only. The service period of the ONE_TIME line item.

ProcessingState

The processing state of a subscription which is transient.

Enums
PROCESSING_STATE_UNSPECIFIED The processing state is unspecified.
PROCESSING_STATE_CANCELLING The subscription is being cancelled.
PROCESSING_STATE_RECURRING The subscription is recurring.

PromotionSpec

Describes the spec for one promotion.

Fields
promotion

string

Required. Promotion resource name that identifies a promotion. The format is 'partners/{partner_id}/promotions/{promotion_id}'.

type

PromotionType

Output only. The type of the promotion for the spec.

Union field spec.

spec can be only one of the following:

introductory_pricing_details

IntroductoryPricingDetails

Output only. The details of the introductory pricing spec if the promotion is of type INTRODUCTORY_PRICING.

free_trial_duration

Duration

Output only. The duration of the free trial if the promotion is of type FREE_TRIAL.

State

The state of a subscription.

Enums
STATE_UNSPECIFIED The state is unspecified.
STATE_CREATED The subscription is created, a state before it is moved to STATE_ACTIVE.
STATE_ACTIVE The subscription is active.
STATE_CANCELLED The subscription is cancelled. This is the final state of the subscription, as it can no longer be modified or reactivated.
STATE_IN_GRACE_PERIOD The subscription is in grace period. It can happen: 1) in manual extend mode, the subscription is not extended by the partner at the end of current cycle. 2) for outbound authorization enabled partners, a renewal purchase order is rejected.
STATE_CANCEL_AT_END_OF_CYCLE The subscription is waiting to be cancelled by the next recurrence cycle.
STATE_SUSPENDED The subscription is suspended.

UpgradeDowngradeDetails

Details about the previous subscription that this new subscription upgrades/downgrades from.

Fields
previous_subscription_id

string

Required. The previous subscription id to be replaced. This is not the full resource name, use the subscription_id segment only.

billing_cycle_spec

BillingCycleSpec

Required. Specifies the billing cycle spec for the new upgraded/downgraded subscription.

BillingCycleSpec

Specifies the billing cycle spec for the new upgraded/downgraded subscription.

Enums
BILLING_CYCLE_SPEC_UNSPECIFIED Billing cycle spec is not specified.
BILLING_CYCLE_SPEC_ALIGN_WITH_PREVIOUS_SUBSCRIPTION The billing cycle of the new subscription aligns with the previous subscription it upgrades or downgrades from.
BILLING_CYCLE_SPEC_START_IMMEDIATELY The billing cycle of the new subscription starts immediately.

UndoCancelSubscriptionRequest

Request to revoke a cancellation request.

Fields
name

string

Required. The name of the subscription resource whose pending cancellation needs to be undone. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

UndoCancelSubscriptionResponse

Response that contains the updated subscription resource.

Fields
subscription

Subscription

The updated subscription resource.

Unit

Frequency of the period.

Enums
UNIT_UNSPECIFIED Default value, reserved as an invalid or an unexpected value.
MONTH Unit of a calendar month.
DAY Unit of a day.
HOUR Unit of an hour. It is used for testing.

UnitLevelDetails

Details about a subset of units in a given process.

Fields
price_details

PriceDetails

Optional. The pricing details about units in a given process.

UserSession

[Preview only] Preview APIs are working in progress and are subject to change. A user session which includes information required to interact with Google Payments Reseller Platform.

Fields
token

string

Output only. The encrypted token of the user session, including the information of the user's intent and request. This token should be provided when redirecting the user to Google.

expire_time

Timestamp

Output only. The time at which the user session expires.

YoutubePayload

Payload specific to Youtube products.

Fields
partner_eligibility_ids[]

string

The list of eligibility_ids which are applicable for the line item.

access_end_time

Timestamp

Output only. The access expiration time for this line item.

partner_plan_type

PartnerPlanType

Optional. Specifies the plan type offered to the end user by the partner.

PartnerPlanType

Partner side plan type.

Enums
PARTNER_PLAN_TYPE_UNSPECIFIED Unspecified. Should not use, reserved as an invalid value.
PARTNER_PLAN_TYPE_STANDALONE This item is offered as a standalone product to the user.
PARTNER_PLAN_TYPE_HARD_BUNDLE This item is bundled with another partner offering, the item is provisioned at purchase time.
PARTNER_PLAN_TYPE_SOFT_BUNDLE This item is bundled with another partner offering, the item is provisioned after puchase, when the user opts in this Google service.