After you retrieve a subscription, you can use the information from the successful response to change the status of the subscription or update the subscription. This page focuses on the different ways that you can retrieve and update a subscription.
Retrieve a subscription
To retrieve a successfully ordered or transferred subscription, use the
following GET
HTTP request.
GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.SUBSCRIPTION_ID
: The subscription identifier that is unique for each customer. You can retrieve this value by using the Retrieve all reseller subscriptions method.
This operation has no parameters in the request body.
A successful response returns an HTTP 200
status
code and the subscription's settings. In the following example response, the
isInTrial
property is false
but there is no
trialEndTime
property, meaning this customer has never been in a
30-day free trial with this plan.
{
"kind": "reseller#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"billingMethod": "ONLINE",
"creationTime": "1331647980142",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
},
"purchaseOrderId": "example.com_annual_1",
"status": "ACTIVE",
"resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
"skuName": "Google Workspace Business Standard"
}
Retrieve all subscriptions for a customer
To retrieve all of a specific reseller customer's subscriptions that have been
successfully ordered or transferred, use the following GET
HTTP request and
include the authorization token:
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.START_DATE
: The start date in the formatYYYY-MM-DD
.MAX_NUMBER
: The maximum number of results returned on a response page.
This operation has no parameters in the request body.
A successful response returns a HTTP 200
status code and a list of the
customer's subscriptions and settings. The list of subscriptions might include
products that aren't managed in this version of the Reseller API.
If you don't manage this customer isn't managed, a 403 "Forbidden"
error is
returned.
Retrieve all transferable subscriptions for a customer
To retrieve all of a customer's subscriptions that potentially could be
transferred to the reseller's management, use the following GET
HTTP request
and include the authorization token. The
customerId
is required and is the customer's unique identifier returned when
retrieving a resold customer's account.
ThecustomerAuthToken
is a transfer token provided by your customer that is
specific to your reseller ID. Once generated by the customer, it is valid for
30 days. For more information about how customers generate the token, see
Transfer your Google Workspace account to a reseller.
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.AUTH_TOKEN
: A transfer token provided by your customer that's specific to your reseller ID. After it's generated by the customer, it's valid for 30 days. For more information about how customers generate the token, see Transfer your Google Workspace account to a reseller. If this value isn't valid or has expired, the API response returns a403 "Forbidden"
error.START_DATE
: The start date in the formatYYYY-MM-DD
.MAX_NUMBER
: The maximum number of results returned on a response page.
This operation has no parameters in the request body.
A successful response returns a HTTP 200
status code and a list of the
customer's transferable subscriptions with the expiration date of the transfer
token and the minimum number of seats needed in the transfer order. A customer
might hold additional subscriptions that aren't transferable.
{
"kind": "reseller#subscriptions",
"subscriptions": [
{
"kind": "subscriptions#subscription",
"customerId": "custId-6543",
"subscriptionId": "432",
"skuId": "1010020028",
"billingMethod": "ONLINE",
"creationTime": "1331647980142",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10,
"maximumNumberOfSeats": 500,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"transferInfo": {
"transferabilityExpirationTime": "1333183980142",
"minimumTransferableSeats": "20"
},
"purchaseOrderId": "PO_890",
"status": "ACTIVE",
"resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
"skuName": "Google Workspace Business Standard"
},
{
"kind": "subscriptions#subscription",
"customerId": "custId-6543",
"subscriptionId": "140",
"skuId": "1010020028",
"creationTime": "1329389322728",
"plan": {
"planName": "FLEXIBLE",
"isCommitmentPlan": false
},
"seats": {
"kind": "subscriptions#seats",
"maximumNumberOfSeats": 50
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false,
"trialEndTime": "1331877480016"
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"transferInfo": {
"transferabilityExpirationTime": "1333183780159",
"minimumTransferableSeats": "10"
},
"purchaseOrderId": "",
"status": "ACTIVE",
"resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
"skuName": "Google Workspace Business Standard"
},
],
"nextPageToken": "token"
}
If you're planning on transferring these subscriptions by using the batch
operation, transfer all of the subscriptions. Transferring each subscription
one-by-one results in an error. In addition, the batch operation only transfers
subscriptions with an ACTIVE
status. For more information, see
Transfer a subscription.
Retrieve all reseller subscriptions
To retrieve all of a reseller's successfully ordered or transferred
subscriptions, use the following GET
HTTP request and include the authorization token.
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER
Replace the following:
PREFIX
: The beginning of the customer's name whose subscriptions you're looking for.TOKEN
: A token identifying a specific page of results the server should return.MAX_NUMBER
: The maximum number of results returned on a response page.
This operation can use the OAuth read-only access scope. The
customerNamePrefix
, pageToken
, and maxResults
are optional query strings.
The following example retrieves all of a reseller's subscriptions that belong to customers whose name begin with 'exam':
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam
{
"kind": "reseller#subscriptions",
"subscriptions": [
{
"kind": "subscriptions#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"creationTime": "1331647980142",
"billingMethod": "ONLINE",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"purchaseOrderId": "PO_135",
"status": "ACTIVE",
"resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
"skuName": "Google Workspace Business Standard"
},
{
"kind": "subscriptions#subscription",
"customerId": "custId-5678",
"subscriptionId": "1404686",
"skuId": "1010020028",
"billingMethod": "ONLINE",
"creationTime": "1329389322728",
"plan": {
"planName": "FLEXIBLE",
"isCommitmentPlan": false
},
"seats": {
"kind": "subscriptions#seats",
"maximumNumberOfSeats": 50,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false,
"trialEndTime": "1331877480016"
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "AUTO_RENEW"
},
"purchaseOrderId": "",
"status": "ACTIVE",
"resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
"skuName": "Google Workspace Business Standard"
},
],
"nextPageToken": "token"
}
Update a subscription plan
Updating Google Workspace plans differs depending on the plan. Before you update a plan, consider the following:
When you create a subscription and the customer qualifies, the subscription's plan can be a 30-day trial. Both the flexible and annual commitment payment plans can be 30-day free trials. During the trial, you can change the subscription's payment plan to either flexible or annual commitment plans as often as needed. But after the trial ends and the plan becomes active, updating the plan follows the same rules as other subscriptions' active plans. To immediately move a trial subscription to an active plan, start a paid service from a 30-day free trial subscription. For more 30-day trial information and customer qualification rules, see the administration help center.
You can update a flexible plan to an annual commitment plan.
You can't update an annual commitment plan.
Not all plans work with all products. For more information about which products are used by these plans, see Products & SKUs.
To update a plan for a 30-day trial or a flexible plan subscription to an annual
commitment plan, use the following POST
HTTP request:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.SUBSCRIPTION_ID
: The subscription identifier that is unique for each customer. You can retrieve this value by using the Retrieve all reseller subscriptions method.
The following example updates the subscription with the subscriptionId
with
a value of 123. The customerId
is C0123456.
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan
The request body has the following:
{
"kind": "reseller#changePlanRequest",
"planName": "ANNUAL_MONTHLY_PAY",
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10
},
"purchaseOrderId": "123_March2012"
}
A successful response returns an HTTP 201
status code and returns the updated
subscription plan settings:
{
"kind": "reseller#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"creationTime": "1331647980142",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"purchaseOrderId": "123_March2012",
"status": "ACTIVE",
"skuName": "Google Workspace Business Standard"
}
Update a subscription's seats
Updating an annual commitment plan subscription uses different subscription properties than updating a Google Workspace flexible plan's subscription.
Update seats for an annual plan's subscription
To update an annual plan subscription's user license settings, use the following
POST
HTTP request:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.SUBSCRIPTION_ID
: The subscription identifier that is unique for each customer. You can retrieve this value by using the Retrieve all reseller subscriptions method.
The following example updates the subscription with the 123 subscriptionId
. The
customerId
is C0123456. The body of the request differs depending on the
type of plan:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats
A Google Workspace annual commitment plan's subscription uses this request body to
update the number of user licenses. The numberOfSeats
value is a
total. For example, if you previously had 10 user licenses and you have a
customer order for 5 new licenses, the total in the request's body for
numberOfSeats
is 15, as shown in the following example:
{
"kind": "subscriptions#seats",
"numberOfSeats": 15
}
Update seats for a flexible plan's subscription
A Google Workspace flexible plan's subscription uses the request body to update
the user licenses. The maximumNumberOfSeats
value is the total of
existing licenses and the new licenses. This is the maximum number of user
licenses that the account can provision.
{
"kind": "subscriptions#seats",
"maximumNumberOfSeats": 15
}
A successful response returns a HTTP 201
status code and the updated
subscription license settings:
{
"kind": "reseller#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"creationTime": "1331647980142",
"plan": {
"planName": "FLEXIBLE",
"isCommitmentPlan": false
},
"seats": {
"kind": "subscriptions#seats",
"maximumNumberOfSeats": 15,
"licensedNumberOfSeats": 10
},
"trialSettings": {
"isInTrial": false
},
"skuName": "Google Workspace Business Standard"
}
Update a subscription's renewal settings
To update an annual commitment subscription's renewal settings, use the
following POST
HTTP request:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.SUBSCRIPTION_ID
: The subscription identifier that is unique for each customer. You can retrieve this value by using the Retrieve all reseller subscriptions method.
The following is an example request body:
{
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}
The renewalType
property's value can be any of the following:
AUTO_RENEW_YEARLY_PAY
: At the end of an annual commitment plan's interval, automatically renew the subscription's plan asANNUAL_YEARLY_PAY
with the samenumberOfSeats
.AUTO_RENEW_MONTHLY_PAY
: At the end of an annual commitment plan's interval, automatically renew the subscriptions's plan asANNUAL_MONTHLY_PAY
with the samenumberOfSeats
.RENEW_CURRENT_USERS_YEARLY_PAY
: At the end of an annual commitment plan's interval, renew the subscription's plan asANNUAL_YEARLY_PAY
but use the total number of current active user licenses. This is the default setting for active annual commitment plans (paid yearly).RENEW_CURRENT_USERS_MONTHLY_PAY
: At the end of an annual commitment plan's interval, renew the subscription's plan asANNUAL_MONTHLY_PAY
but use the total number of current active user licenses. This is the default setting for active annual commitment plans (paid monthly).RENEW_ON_PROPOSED_OFFER
: At the end of the current commitment plan's interval, renew on the latest renewal proposal with numberOfSeats as number of current active user licenses or proposed offer commitment whichever is higher.SWITCH_TO_PAY_AS_YOU_GO
: At the end of an annual commitment plan's interval, change the annual commitment plan to a flexible plan.CANCEL
: At the end of an annual commitment plan interval, the subscription is suspended. To understand how to lift a suspension, see the administration help center.
A successful response returns a HTTP 201
status code and the updated
subscription renewal settings:
{
"kind": "reseller#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"creationTime": "1331647980142",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 15,
"licensedNumberOfSeats": 15
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"skuName": "Google Workspace Business Standard"
}
Start paid service from a free trial subscription
To immediately move a 30-day free trial subscription to a paid service
subscription, if a payment plan has already been set up for the trial
subscription, use the following POST
HTTP request.
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.SUBSCRIPTION_ID
: The subscription identifier that is unique for each customer. You can retrieve this value by using the Retrieve all reseller subscriptions method.
The following example has C0123456 as the customerId
and the
subscriptionId
value of 123:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService
This operation has no parameters in the request body.
A successful response returns a HTTP 201
status code and the updated subscription settings:
{
"kind": "reseller#subscription",
"customerId": "C0123456",
"subscriptionId": "123",
"skuId": "1010020028",
"creationTime": "1331647980142",
"plan": {
"planName": "ANNUAL",
"isCommitmentPlan": true,
"commitmentInterval": {
"startTime": "1331647980142",
"endTime": "1363183980142"
}
},
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 15,
"licensedNumberOfSeats": 15
},
"trialSettings": {
"isInTrial": false
},
"renewalSettings": {
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
},
"skuName": "Google Workspace Business Standard"
}
Upgrade or downgrade a subscription
You can't downgrade annual plans in the middle of their term, and you can't
schedule a downgrade by using renewal settings. We recommend that you set
renewal settings to switch to FLEXIBLE
and then downgrade after renewal time.
To upgrade or downgrade a subscription, create a new subscription
with the skuId
that you want to upgrade or downgrade to.
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions
Replace the following:
CUSTOMER_ID
: Either the customer's primary domain name or the customer's unique identifier.
This call terminates the previous subscription and creates a new one.
Find more information about upgrades and downgrades on the Products & SKUs page.