REST Resource: partners.subscriptions

Resource: Subscription

A Subscription resource managed by 3P Partners.

JSON representation 
{
  "name": string,
  "products": [
    string
  ],
  "promotions": [
    string
  ],
  "partnerUserToken": string,
  "serviceLocation": {
    object (Location)
  },
  "upgradeDowngradeDetails": {
    object (UpgradeDowngradeDetails)
  },
  "redirectUri": string,
  "createTime": string,
  "updateTime": string,
  "cycleEndTime": string,
  "freeTrialEndTime": string,
  "endUserEntitled": boolean,
  "state": enum (State),
  "cancellationDetails": {
    object (CancellationDetails)
  }
}
Fields
name

string

Output only. Response only. Resource name of the subscription. It will have the format of "partners/{partner_id}/subscriptions/{subscriptionId}"
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}'.
partnerUserToken

string

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

object (Location)

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

object (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.
redirectUri

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.
createTime

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
cycleEndTime

string (Timestamp format)

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"

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
freeTrialEndTime

string (Timestamp format)

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.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endUserEntitled

boolean

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

enum (State)

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

object (CancellationDetails)

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

Location

Describes a location of an end user.

JSON representation 
{
  "regionCode": string,
  "postalCode": string
}
Fields
regionCode

string

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

string

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

UpgradeDowngradeDetails

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

JSON representation 
{
  "previousSubscriptionId": string,
  "billingCycleSpec": enum (BillingCycleSpec)
}
Fields
previousSubscriptionId

string

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

enum (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.

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.

CancellationDetails

Describes the details of a cancelled subscription.

JSON representation 
{
  "reason": enum (CancellationReason)
}
Fields
reason

enum (CancellationReason)

The reason of the cancellation.

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.

Methods

cancel

 Used by partners to cancel a subscription service by the end of the current billing cycle for their customers.

create

 Used by partners to create a subscription for their customers.

entitle

 Used by partners to entitle a previously provisioned subscription to the current end user.

extend

 Used by partners to extend a subscription service for their customers.

get

 Used by partners to get a subscription by id.

provision

 Used by partners to provision a subscription for their customers.

undoCancel

 Used by partners to revoke the pending cancellation of a subscription, which is currently in STATE_CANCEL_AT_END_OF_CYCLE state.