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

Index

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 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)

Used by partners to extend a subscription service for their customers. It should be called directly by the partner using service accounts.

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)

Used by partners to list products that can be resold to their customers. It should be called directly by the partner using service accounts.

ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

Used by partners to list promotions, such as free trial, that can be applied on subscriptions. It should be called directly by the partner using service accounts.

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)

Used by partners to revoke 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. It should be called directly by the partner using service accounts.

CancelSubscriptionRequest

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, the subscription will be cancelled immediately. Otherwise, the subscription will be cancelled at the end of the current cycle, and therefore no prorated refund will be issued for the rest of the cycle.

CancelSubscriptionResponse

Fields
subscription

Subscription

The cancelled subscription resource.

CancellationReason

Describes the reason for cancellation of the subscription.

Enums
CANCELLATION_REASON_UNSPECIFIED Reason is unspecified.
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 User account closed.
CANCELLATION_REASON_UPGRADE_DOWNGRADE Used for notification only, do not use in Cancel API. Cancallation due to upgrade or downgrade.
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}"

EntitleSubscriptionResponse

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. A random UUID is recommended.

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

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"

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

Specifies the period of access the subscription should grant.

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}"

ListProductsRequest

Fields
parent

string

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

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

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

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 defined in the EBNF grammar: https://google.aip.dev/assets/misc/ebnf-filtering.txt. Examples:

  • applicable_products: "sku1"
  • region_codes: "US"
  • applicable_products: "sku1" AND region_codes: "US"
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

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"

Product

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

Fields
name

string

Output only. Response only. Resource name of the subscription. 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

Promotion

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

Fields
name

string

Output only. 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

Output only. Specifies the duration of the free trial of the subscription.

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.

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.

Subscription

A Subscription resource managed by 3P Partners.

Fields
name

string

Output only. Response only. Resource name of the subscription. It will have the format of "partners/{partner_id}/subscriptions/{subscription_id}"

products[]

string

Required. Resource name that identifies one or more subscription products. The format will be 'partners/{partner_id}/products/{product_id}'.

promotions[]

string

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}'.

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.

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"

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. Descibes the 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.

CancellationDetails

Describes the details of a cancelled subscription.

Fields
reason

CancellationReason

The reason of the cancellation.

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.
STATE_IN_GRACE_PERIOD The subscription has not been extended by the partner after the end of current cycle.
STATE_CANCEL_AT_END_OF_CYCLE The subscription is waiting to be cancelled by the next recurrence cycle.

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.
MONTH Unit of a calendar month.
DAY Unit of a day.