# REST Resource: subscriptions

- [Resource: Subscription](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Subscription)
  - [JSON representation](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Subscription.SCHEMA_REPRESENTATION)
    - [JSON representation](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Subscription.SCHEMA_REPRESENTATION.plan.SCHEMA_REPRESENTATION)
- [Seats](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Seats)
  - [JSON representation](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Seats.SCHEMA_REPRESENTATION)
- [RenewalSettings](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#RenewalSettings)
  - [JSON representation](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#RenewalSettings.SCHEMA_REPRESENTATION)
- [Methods](https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#METHODS_SUMMARY)

## Resource: Subscription

JSON template for a subscription.

| JSON representation |
|---|
| ``` { "customerId": string, "subscriptionId": string, "skuId": string, "creationTime": string, "kind": string, "seats": { object (`https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Seats`) }, "renewalSettings": { object (`https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#RenewalSettings`) }, "purchaseOrderId": string, "status": string, "resourceUiUrl": string, "billingMethod": string, "suspensionReasons": [ string ], "customerDomain": string, "dealCode": string, "skuName": string, "plan": { "planName": string, "isCommitmentPlan": boolean, "commitmentInterval": { "startTime": string, "endTime": string } }, "trialSettings": { "isInTrial": boolean, "trialEndTime": string }, "transferInfo": { "transferabilityExpirationTime": string, "minimumTransferableSeats": integer, "currentLegacySkuId": string } } ``` |

| Fields ||
|---|---|
| `customerId` | `string` This property will always be returned in a response as the unique identifier generated by Google. In a request, this property can be either the primary domain or the unique identifier generated by Google. |
| `subscriptionId` | `string` The `subscriptionId` is the subscription identifier and is unique for each customer. This is a required property. Since a `subscriptionId` changes when a subscription is updated, we recommend not using this ID as a key for persistent data. Use the `subscriptionId` as described in [retrieve all reseller subscriptions](https://developers.google.com/workspace/admin/reseller/v1/how-tos/manage_subscriptions#get_all_subscriptions). |
| `skuId` | `string` A required property. The `skuId` is a unique system identifier for a product's SKU assigned to a customer in the subscription. For products and SKUs available in this version of the API, see [Product and SKU IDs](https://developers.google.com/workspace/admin/reseller/v1/how-tos/products). |
| `creationTime` | `string (https://developers.google.com/discovery/v1/type-format format)` The `creationTime` property is the date when subscription was created. It is in milliseconds using the Epoch format. See an example [Epoch converter](http://www.epochconverter.com/). |
| `kind` | `string` Identifies the resource as a Subscription. Value: `reseller#subscription` |
| `seats` | ``object (`https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#Seats`)`` This is a required property. The number and limit of user seat licenses in the plan. |
| `renewalSettings` | ``object (`https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions#RenewalSettings`)`` Renewal settings for the annual commitment plan. For more detailed information, see renewal options in the [administrator help center](https://support.google.com/a/bin/answer.py?topic=1247359&ctx=topic&answer=2500693). |
| `purchaseOrderId` | `string` This is an optional property. This purchase order (PO) information is for resellers to use for their company tracking usage. If a `purchaseOrderId` value is given it appears in the API responses and shows up in the invoice. The property accepts up to 80 plain text characters. |
| `status` | `string` This is an optional property. |
| `resourceUiUrl` | `string` URL to customer's Subscriptions page in the Admin console. The read-only URL is generated by the API service. This is used if your client application requires the customer to complete a task using the Subscriptions page in the Admin console. |
| `billingMethod` | `string` Read-only field that returns the current billing method for a subscription. |
| `suspensionReasons[]` | `string` Read-only field containing an enumerable of all the current suspension reasons for a subscription. It is possible for a subscription to have many concurrent, overlapping suspension reasons. A subscription's `STATUS` is `SUSPENDED` until all pending suspensions are removed. Possible options include: - `PENDING_TOS_ACCEPTANCE` - The customer has not logged in and accepted the G Suite Resold Terms of Services. - `RENEWAL_WITH_TYPE_CANCEL` - The customer's commitment ended and their service was cancelled at the end of their term. - `RESELLER_INITIATED` - A manual suspension invoked by a Reseller. - `TRIAL_ENDED` - The customer's trial expired without a plan selected. - `OTHER` - The customer is suspended for an internal Google reason (e.g. abuse or otherwise). <br /> |
| `customerDomain` | `string` Primary domain name of the customer |
| `dealCode` | `string` Google-issued code (100 char max) for discounted pricing on subscription plans. Deal code must be included in `insert` requests in order to receive discounted rate. This property is optional, regular pricing applies if left empty. |
| `skuName` | `string` Read-only external display name for a product's SKU assigned to a customer in the subscription. SKU names are subject to change at Google's discretion. For products and SKUs available in this version of the API, see [Product and SKU IDs](https://developers.google.com/workspace/admin/reseller/v1/how-tos/products). |
| `plan` | `object` The `plan` property is required. In this version of the API, the G Suite plans are the flexible plan, annual commitment plan, and the 30-day free trial plan. For more information about the API"s payment plans, see the [API concepts](https://developers.google.com/workspace/admin/reseller/v1/how-tos/concepts#plans). |
| `plan.planName` | `string` The `planName` property is required. This is the name of the subscription's plan. For more information about the Google payment plans, see the [API concepts](https://developers.google.com/workspace/admin/reseller/v1/how-tos/concepts#plans). Possible values are: - `ANNUAL_MONTHLY_PAY` --- The annual commitment plan with monthly payments. > [!CAUTION] > **Caution:** `ANNUAL_MONTHLY_PAY` is returned as `ANNUAL` in all API responses. - `ANNUAL_YEARLY_PAY` --- The annual commitment plan with yearly payments - `FLEXIBLE` --- The flexible plan - `TRIAL` --- The 30-day free trial plan. A subscription in trial will be suspended after the 30th free day if no payment plan is assigned. Calling `changePlan` will assign a payment plan to a trial but will not activate the plan. A trial will automatically begin its assigned payment plan after its 30th free day or immediately after calling `startPaidService`. - `FREE` --- The free plan is exclusive to the Cloud Identity SKU and does not incur any billing. <br /> |
| `plan.isCommitmentPlan` | `boolean` The `isCommitmentPlan` property's boolean value identifies the plan as an annual commitment plan: - `true` --- The subscription's plan is an annual commitment plan. - `false` --- The plan is not an annual commitment plan. <br /> |
| `plan.commitmentInterval` | `object` In this version of the API, annual commitment plan's interval is one year. > [!CAUTION] > **Note:** When `billingMethod` value is `OFFLINE`, the subscription property object `plan.commitmentInterval` is omitted in all API responses. <br /> |
| `plan.commitmentInterval.startTime` | `string (https://developers.google.com/discovery/v1/type-format format)` An annual commitment plan's interval's `startTime` in milliseconds using UNIX Epoch format. See an example [Epoch converter](http://www.epochconverter.com/). |
| `plan.commitmentInterval.endTime` | `string (https://developers.google.com/discovery/v1/type-format format)` An annual commitment plan's interval's `endTime` in milliseconds using the UNIX Epoch format. See an example [Epoch converter](http://www.epochconverter.com/). |
| `trialSettings` | `object` The G Suite annual commitment and flexible payment plans can be in a 30-day free trial. For more information, see the [API concepts](https://developers.google.com/workspace/admin/reseller/v1/how-tos/concepts#plans). |
| `trialSettings.isInTrial` | `boolean` Determines if a subscription's plan is in a 30-day free trial or not: - `true` --- The plan is in trial. - `false` --- The plan is not in trial. <br /> |
| `trialSettings.trialEndTime` | `string (https://developers.google.com/discovery/v1/type-format format)` Date when the trial ends. The value is in milliseconds using the UNIX Epoch format. See an example [Epoch converter](http://www.epochconverter.com/). |
| `transferInfo` | `object` Read-only transfer related information for the subscription. For more information, see [retrieve transferable subscriptions for a customer](https://developers.google.com/workspace/admin/reseller/v1/how-tos/manage_subscriptions#get_transferable_subscriptions). |
| `transferInfo.transferabilityExpirationTime` | `string (https://developers.google.com/discovery/v1/type-format format)` The time when transfer token or intent to transfer will expire. The time is in milliseconds using UNIX Epoch format. |
| `transferInfo.minimumTransferableSeats` | `integer` When inserting a subscription, this is the minimum number of seats listed in the transfer order for this product. For example, if the customer has 20 users, the reseller cannot place a transfer order of 15 seats. The minimum is 20 seats. |
| `transferInfo.currentLegacySkuId` | `string` The `skuId` of the current resold subscription. This is populated only when the customer has a subscription with a legacy SKU and the subscription resource is populated with the `skuId` of the SKU recommended for the transfer. |

## Seats

JSON template for subscription seats.

| JSON representation |
|---|
| ``` { "numberOfSeats": integer, "maximumNumberOfSeats": integer, "licensedNumberOfSeats": integer, "kind": string } ``` |

| Fields ||
|---|---|
| `numberOfSeats` | `integer` This is a required property and is exclusive to subscriptions with `ANNUAL_MONTHLY_PAY` and `ANNUAL_YEARLY_PAY` plans. This property sets the maximum number of licenses assignable to users on a subscription. The reseller can add more licenses, but once set, the `numberOfSeats` cannot be reduced until renewal. The reseller is invoiced based on the `numberOfSeats` value regardless of how many of these user licenses are assigned. > [!NOTE] > **Note:**Google Workspace subscriptions automatically assign a license to every user. <br /> |
| `maximumNumberOfSeats` | `integer` This is a required property and is exclusive to subscriptions with `FLEXIBLE` or `TRIAL` plans. This property sets the maximum number of licensed users allowed on a subscription. This quantity can be increased up to the maximum limit defined in the reseller's contract. The minimum quantity is the current number of users in the customer account. > [!NOTE] > **Note:**G Suite subscriptions automatically assign a license to every user. <br /> |
| `licensedNumberOfSeats` | `integer` Read-only field containing the current number of users that are assigned a license for the product defined in `skuId`. This field's value is equivalent to the numerical count of users returned by the Enterprise License Manager API method: [`listForProductAndSku`](https://developers.google.com/workspace/admin/licensing/v1/reference/licenseAssignments/listForProductAndSku). |
| `kind` | `string` Identifies the resource as a subscription seat setting. Value: `subscriptions#seats` |

## RenewalSettings

JSON template for a subscription renewal settings.

| JSON representation |
|---|
| ``` { "renewalType": string, "kind": string } ``` |

| Fields ||
|---|---|
| `renewalType` | `string` Renewal settings for the annual commitment plan. For more detailed information, see renewal options in the [administrator help center](https://support.google.com/a/bin/answer.py?topic=1247359&ctx=topic&answer=2500693). When renewing a subscription, the `renewalType` is a required property. |
| `kind` | `string` Identifies the resource as a subscription renewal setting. Value: `subscriptions#renewalSettings` |

| ## Methods ||
|---|---|
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/activate` | Activates a subscription previously suspended by the reseller. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/changePlan` | Updates a subscription plan. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/changeRenewalSettings` | Updates a user license's renewal settings. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/changeSeats` | Updates a subscription's user license settings. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/delete` | Cancels, suspends, or transfers a subscription to direct. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/get` | Gets a specific subscription. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/insert` | Creates or transfer a subscription. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/list` | Lists of subscriptions managed by the reseller. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/startPaidService` | Immediately move a 30-day free trial subscription to a paid service subscription. |
| ### `https://developers.google.com/workspace/admin/reseller/reference/rest/v1/subscriptions/suspend` | Suspends an active subscription. |