Retrieve & update a subscription

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 GETHTTP 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 format YYYY-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 a 403 "Forbidden" error.
START_DATE: The start date in the format YYYY-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 as ANNUAL_YEARLY_PAY with the same numberOfSeats.
AUTO_RENEW_MONTHLY_PAY: At the end of an annual commitment plan's interval, automatically renew the subscriptions's plan as ANNUAL_MONTHLY_PAY with the same numberOfSeats.
RENEW_CURRENT_USERS_YEARLY_PAY: At the end of an annual commitment plan's interval, renew the subscription's plan as ANNUAL_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 as ANNUAL_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.